agentrun/README.md at main · Parcha-ai/agentrun
AgentRun is an open-source platform that supercharges your agents. It adds self-improvement, durable execution and a control plane on top of your favorite agent harness. Your agents become smarter,...
AgentRun is an open-source platform that supercharges your agents. It adds self-improvement, durable execution and a control plane on top of your favorite agent harness. Your agents become smarter,...
Run smarter agents. Use fewer tokens.
Our code review bill went up 36x this year. Now a review costs us 18 cents. See how ↓
AgentRun Cloud · Run locally · Self-host
Quickstart · Connect your agent · Case studies · Tour · Templates · Deploy · Docs
An agent's Learning tab: what it kept, and what changed since. Demo data from the console's recorded fixtures.
Code review. Greptile started charging a dollar a review in March, then our agents took off, and our bill went from $180 a month to $6,451. So we built our own reviewer on a cheap model and tuned it on our own PRs. It costs 18 cents a review, and on 30 PRs it had never seen it caught 1.6x the real bugs Greptile did. How we built it · Tune one on your repo
Merchant codes. We let Opus figure out how to classify merchants, then handed what it learned to a cheap model. Same job, $0.89 down to $0.12 a merchant. How it works · Do it with your own job
Agents are great at figuring things out. The problem is they figure out the same things over and over. Give an agent a job it has done a hundred times and it rediscovers the same API, rereads the same docs and rebuilds the same plan, and you pay for every token of it.
Bring your agent on the harness it runs best on: Claude Code, Codex, OpenCode or pi. AgentRun does everything around it:
You don't build the plumbing: provider integrations, recovery, run tracking and learning are all here. Use AgentRun Cloud for hosted access, or run the open-source platform on your laptop, in one container, or as a server with runners. Apache-2.0.
AgentRun Cloud. Run agents without maintaining your own server. Open Cloud to create an account or sign in. For help setting up your team's workflows, talk to us.
Prefer your own machine or infrastructure? Start locally below, or self-host on Render or Docker. The getting-started guide explains the three options.
You need Node 24.22.3 or newer, on macOS or Linux.
Already use Claude Code or Codex? Connect your existing agent with its current configuration and sign-in. You do not need to add a model key to AgentRun for that connection. The steps below start a new agent from a template.
Start it.
npx @parcha/agentrun
It starts the server and one runner on port 7340 (or the next free one), keeps everything in ~/.agentrun, and
opens the console in your browser.
Rather have your coding agent do it? For the published quickstart, tell it:
Read agentrun.ai/SKILL.md and set up AgentRun locally for me.
For this development checkout, point it to the matching onboarding skill, which guides either
starting a new agent or bringing an existing one. The public website's skill is released separately.
If Docker is running on your machine, new agents get a Docker sandbox with a shell. Its image builds on first use, which takes a few minutes, and the console says when it's ready. Without Docker, agents still read and write files, but get no shell.
Want your own server with a URL? Self-host on Render.
Already have agents running in a backend, Docker deployment or terminal? Connect agent can observe them through the same CLI and OpenTelemetry Collector used by hosted AgentRun. The OSS console shows their reported activity and token usage while your application keeps starting the work. Follow Observe agents that already run elsewhere. Observation needs no model key and does not automatically enable learning or import transcripts.
Keep the project, instructions, skills, MCP tools and sign-in you already use in Claude Code or Codex. AgentRun can start new jobs with that setup and show their activity and results in the console.
Development build: remote connections currently require the server and the Python connector from the same reviewed checkout. The published observation-only CLI does not include this remote execution mode. Follow the source connector setup for installation and the matching Node bridge.
History import brings selected completed conversations into Runs without executing them or automatically training the agent. A live connection starts new CLI sessions; it does not attach to a desktop conversation already in progress. You can connect first and import history later with an explicitly approved history scope.
Connection and history guide · Remote CLI installation and commands
Already run an agent inside your backend with an SDK? The development build can add checked learning around its existing call site. Your backend keeps its job queue, tools, model credentials and cancellation; AgentRun records the run and supplies accepted learning to the next fresh task. Use the matching client and server from this checkout.
| Backend SDK | Integration |
|---|---|
| Claude Agent SDK | Wrap your existing query and custom tools |
| Codex SDK | Wrap your existing Codex client and fresh threads |
The live examples verify native tool execution, an accepted note or skill, fresh-run reuse, and a learning-Off control. Reflection and independent grading run on the server and add model usage.
Workflows that make the call. A step can ask a fast typed question, see how sure the answer is, and pick a route. Here the model leans approve at 0.61, below the workflow's 0.75 bar, so the case goes to review.
Every agent in one place. Mission Control opens first: what needs you, what failed, what's running and what it cost, by day, by harness and by tool.
Every agent is an API. Start a run from the Playground, then copy the same request into your code.
You stay in control. An agent can stop and ask you, and the run waits until you answer.
Turn it on with "learning": true in an agent's definition. At the end of every run, the agent gets one more turn to
say what it would keep. AgentRun checks it, grades it, and commits the keepers to the agent's own git folder. The next
run starts from there.
flowchart LR
start["Run starts from<br/>the agent's main"] --> work["Run does the job"]
work --> propose["Last turn proposes<br/>notes, a skill, a workflow"]
propose --> check["Code checks,<br/>then one grader"]
check -->|kept| commit["Commit to main"]
commit --> start
Loading
The agent's Learning tab shows every note, skill and workflow and the log of changes, and each run shows which
notes it was given and opened. Retire anything there, or with npx @parcha/agentrun learning retire and the note's
ETag. Git keeps the history, so a retired note can come back.
Each agent has a learning folder: plain git with one branch, main. A run reads the index of active notes in its
instructions and gets the learned skills beside its own. Code checks every proposal first. An item that breaks a rule of
its own (a size or count limit, its name, its shape) is left out and the rest goes on. A secret or a hidden character
anywhere in the answer, a file outside the folder, a deletion or a full index drops the whole answer, since no item of
it can be trusted. Then one grader judges what it says, and AgentRun commits what passes. A risky rule waits for your
OK. A rule the run found in a page or a pasted email, or a note that holds an account number, is dropped.
Once an agent's notes outgrow the learning budget, each run gets the ones that bear on its first message, whole, and a line for each of the rest. A run that only ran a learned workflow isn't asked what to keep.
A lot of agents don't need to be agents. Write repeatable work as a typed workflow: tool calls, model steps and fast typed decisions (yes or no, pick one, a score, each with its confidence), with an agent to fall back on when a case is unclear. AgentRun runs it as an agent's revision, under the agent's tool permissions and a cap like any run, and a trigger can start one.
An illustration of the control flow in examples/support-answer.mjs, not a recording of a model run.
Watch any workflow run node by node, pause it and resume it, and read every decision and why it was made:
What a workflow looks likeA workflow is a JSON document of typed steps:
{
"v": 2, "name": "read-site",
"schemas": {
"In": { "type": "object", "required": ["website"], "properties": { "website": { "type": "string" } } },
"Page": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean" } } }
},
"input": { "schemaId": "In" },
"output": { "schemaId": "Page", "path": "home" },
"root": { "node": "chain", "steps": [
{ "node": "call", "label": "Read the home page", "via": "tool", "tool": "web_fetch",
"args": { "url": "{website}" }, "out": "Page", "as": "home", "deadline_s": 60 }
] }
}
Steps can call tools, run a model, ask a fast typed question, branch on the answer, map over a list in parallel, loop a
bounded number of times, call other workflows, or hand the hard case to an agent. Save one as an agent's workflow
field; npx @parcha/agentrun workflows validate checks it first. The workflow language also
runs on its own inside your app, with a TypeScript builder.
Every agent, revision, run and step lives in one store. Stop the server mid-run and start it again, and the run carries on. With several runners, another runner picks up a dead runner's runs once their 30-second lease runs out. A finished step is never run again; a write a crash cut off mid-call is marked interrupted rather than retried, so you can check it.
Five ready-made agents. Apply one in one screen, make it yours, and measure it with its own eval cases. Each template is one folder: the agent's instructions, its skills, its rules and its eval cases. Templates → Apply grants nothing until you tick each MCP tool yourself.
| Template | What it does |
|---|---|
code-review |
Reviews a pull request with eight independent reviewers on a read-only checkout (or a pasted diff), merges and verifies their findings, quotes the line behind each, and returns them as JSON. It sets up its own GitHub trigger |
kyb |
Due diligence on one company: registries, owners, sanctions lists, dated adverse media, and a verdict with every claim cited |
market-monitor |
Every Monday, a digest of what changed at the companies you watch, each item dated and linked |
inbound-lead |
Researches each lead a webhook sends and scores it 0 to 100 against your ideal customer profile |
release-notes |
Turns the pull requests merged since the last release into release notes, left as a draft issue for a person |
npx @parcha/agentrun template eval DIR runs a template's eval cases as real runs on a throwaway server and grades
them. Template packages has the folder format.
Want a template to know your code? Tune a template on your own code walks
through the loop we ran on code-review.
Triggers start capped runs on their own: schedules, signed webhooks, GitHub pull request events and Composio events.
Give an agent the tools of any remote MCP server in Settings → MCP servers. With a Composio key, five steps take you from a toolkit to a run that a Composio event starts:
Connect Composio tools and triggers has each step's API call and the Composio side of the trigger.
Harnesses. Name one in the agent's definition with harness. Approvals, caps, computers, triggers and learning work
the same on each. npx @parcha/agentrun server capabilities says which harnesses your server runs.
| Harness | harness |
On a ChatGPT plan | Notes |
|---|---|---|---|
| pi | pi |
Yes | The default |
| Claude Code | claude-agent |
No: an Anthropic or OpenRouter key | Installs itself on first use |
| Codex | codex |
Yes | Installs itself on first use |
| OpenCode | opencode |
No: an OpenAI or OpenRouter key | Needs its opencode-ai package beside the server; AgentRun prints the line that installs it |
Signed in with ChatGPT and no key, Codex and pi agents run on your plan. Claude Code, OpenCode, Jev decisions and paid tools need their own keys.
Computers. An agent gets a computer with one setting. It gets the tools for that kind and nothing else, and changing the computer changes nothing else about the agent.
computer: kind: sandbox # none, sandbox, desktop, phone or browser provider: daytona # one you connected in Settings → Computers (none takes no provider)
| Kind | What the agent can do | Providers |
|---|---|---|
none |
Read and write files in its run folder; no shell (with Archil, commands run on Archil's exec) | none needed |
sandbox |
Run code, install packages, keep processes in the background, on Linux | Docker, Daytona, Modal, E2B |
desktop |
See a Linux screen, move the mouse, type | Orgo, E2B, Docker (your own image with an X server) |
phone |
Tap, swipe, type, open apps and read the screen on Android | phone harness (a rented cloud Android) |
browser |
Browse the web, and hand the controls to you at any point | Browserbase, Kernel |
Every kind but none names its provider. An agent with no computer setting gets the Docker sandbox where the server
has Docker, and no computer otherwise. Remote computers bill through your own account with the vendor.
npm ci && npm run build:
npm run conformance -w @parcha/agentrun-computer -- --provider docker --kind sandbox.@parcha/agentrun-computer is the protocol underneath: one small daemon in every
computer and one provider per vendor. To add your vendor, see How to contribute a provider.
flowchart LR
you["Console · CLI · API"] --> server["Server"]
server --> store["One store<br/>SQLite or Postgres"]
runner["Runners"] -->|claim runs| store
runner --> hands["Hands<br/>run folder + computer"]
Loading
/v2 and the console. It writes runs and commands to the store and reads it back for
you. It runs no agent loop itself when you start it with --no-runner.AGENTRUN_STORE_URL./workspace and the tools run inside it; a desktop, phone or browser leaves the folder on the runner.npx @parcha/agentrun is also the server's CLI. Run these in a second terminal while the server is up; the CLI finds
it and its token by itself. The script makes an agent, starts a run capped at $1, lets the agent ask you a question,
answers it, and reads the file the agent wrote. With Docker on, the first run waits for the sandbox image.
# 1. Make an agent that can write files and ask you things.
cat > agent.json <<'EOF'
{"definition": {"id": "notes", "version": 1, "name": "Notes",
"instructions": "Do what you are asked, and write what you make to a file.",
"skills": [], "tools": ["write", "ask_person"]}}
EOF
npx @parcha/agentrun agents create --body @agent.json
# 2. Start a capped run and wait. It stops to ask you which region (exit code 8: it waits on you).
npx @parcha/agentrun runs start notes --max-cost-usd 1 --wait \
--body '{"input": {"content": "Ask me which region to cover, then write region.md about it."}}' > out.json
# 3. Answer, wait for it to finish, and read what it wrote.
run=$(node -p 'require("./out.json").run_id')
npx @parcha/agentrun runs message "$run" --content "Europe"
npx @parcha/agentrun runs wait "$run" > out.json
npx @parcha/agentrun runs read-file "$run" region.md
runs wait exits 0 when the run completed, 1 when it failed, and 8 when it waits on you: a question, its cap, or an
approval. runs timeline RUN_ID --follow streams each step as it happens, and every run carries a console_url to its
page. npx @parcha/agentrun help lists every command; npx @parcha/agentrun skill install --claude (or --codex)
teaches your coding agent the CLI.
With the TypeScript client (npm install @parcha/agentrun-client, no dependencies). The client reads its server and
token from the environment; the server prints both when it starts (with npx @parcha/agentrun, the token is in
~/.agentrun/.token, and the address is normally http://127.0.0.1:7340):
export AGENTRUN_BASE_URL=http://127.0.0.1:7340/v2 export AGENTRUN_API_KEY=$(cat ~/.agentrun/.token)
import { AgentRun } from "@parcha/agentrun-client";
const client = new AgentRun(); // AGENTRUN_BASE_URL and AGENTRUN_API_KEY
const started = await client.runs.start("notes", { input: { content: "Ask me which region to cover, then write region.md about it." }, max_cost_usd: 1 });
let run = await client.runs.wait(started.run_id);
if (run.pending?.kind === "question") await client.runs.message(run.run_id, { content: "Europe" });
run = await client.runs.wait(run.run_id);
console.log(run.status, run.cost.usd);
The Python client is pip install parcha-agentrun, with the same methods
(TypeScript client, Python client).
For a hosted workspace, use AgentRun Cloud. The options below deploy the open-source platform on infrastructure you manage. None of them needs a model key: once it's up, Continue with ChatGPT (Settings → Model keys, or the first screen), then run your first agent. Or add a model key there instead.
Your server, your ChatGPT plan, only you: a ChatGPT sign-in is for the person who runs this server. Don't share it or let others run agents on it. Eligible usage in this app uses your ChatGPT plan. Manage usage in your ChatGPT settings. On a server that isn't this computer, the sign-in tab ends on a page that won't load: copy its whole address into the console.
Self-host on Render.
The button deploys render.yaml: one 1 CPU / 2 GB instance with a 10 GB disk, the published image (no
build), and the token and seal key generated for you. It needs a card on your Render workspace: about $25 a month for
the instance and $2.50 for the disk, at Render's prices when this was written. Leave the model keys in Render's form
blank. When it's live, open its URL and paste AGENTRUN_TOKEN from the service's Environment tab to set your password.
Then Continue with ChatGPT (Settings → Model keys, or the first screen), then run your first agent. Or paste a key in
Render's form, or add it in the console: we recommend an OPENROUTER_API_KEY with a dollar cap and an expiration
date. Do not share it with anyone.
On a Linux machine with Docker:
git clone https://github.com/Parcha-ai/agentrun && cd agentrun/deploy printf 'AGENTRUN_SEAL_KEY=%s\n' "$(openssl rand -base64 32)" > .env && chmod 600 .env docker compose up -d --build docker compose logs server # the console's link, the first visit's setup code and, the first time, the token
Open the link, set your password, then Continue with ChatGPT (Settings → Model keys, or the first screen), then run
your first agent. Or add a model key in the console, or in .env before docker compose up
(echo 'OPENROUTER_API_KEY=...' >> .env).
The port is published on this machine's loopback only; put a TLS proxy in front before you open it to anyone else.
This compose file has no Docker socket, so its agents get file tools and web_fetch but no shell. For a Docker
sandbox, use the single-server compose.yaml at the repository's root (Docker Engine 26 or later), run the server on
the host.
Set AGENTRUN_STORE_URL to a postgres:// URL on the server and every runner (the compose file's pg profile runs
one), start the server with --no-runner, and start each runner from the same image with
runner --data /data --name <name>. Give every process the same AGENTRUN_SEAL_KEY. Runners still share the /data
volume in this release.
Deploying AgentRun covers runners, health checks and upgrades.
Every saved secret (model and tool keys, MCP credentials, sign-ins, webhook signing secrets) is sealed under one key,
AGENTRUN_SEAL_KEY; keep it, because losing it loses what it sealed. Secrets are write-only: the console shows each
one as set or missing, and only the console can paste, replace or remove one (your signed-in session, or the
launcher's console on loopback when accounts are off). A key set where the server starts wins over a pasted one. The
API token can't write a secret or approve a tool call. A run gets only the keys its own model and tools need, and
nothing a run learns can keep a secret it was handed. SECURITY.md says how to report a vulnerability.
Apache-2.0. Copyright 2026 Parcha Labs, Inc. Built by Grep.ai.
AgentRun builds on pi by Earendil Works (MIT), the agent loop and durable runtime under it; Stagehand and the Browserbase Node SDK; the TypeSafe JavaScript SDK; Archil's disk SDK; and vercel-labs/durable-harness (Apache-2.0), whose ideas and code the durable harnesses build on. Each keeps its own license; each package's NOTICE lists what it carries.
Texto de github.com tal como lo publicó, leído de su página y mostrado aquí con el formato de El Autómata. El original, en github.com · Volver a la noticia de El Autómata