Run smarter agents. Use fewer tokens.

Quickstart · Tour · Templates · Deploy · Docs

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, more fault tolerant and use fewer tokens with every run.

_{An agent's Learning tab: what it kept, and what changed since. Demo data from the console's recorded fixtures.}

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:

• It learns the work. After each run, the agent keeps what will help next time: a note, a skill, or a workflow that does the job without the loop. The next run starts from there.
• It never loses a run. Every run lives in one store. Kill the server mid-run, start it again, and the run carries on. Give each agent the computer the job needs: a sandbox, a Linux desktop, an Android phone or a browser.
• You stay in control. Approvals, spend caps and one console for every agent: what needs you, what failed, what's running and what it cost.

You don't build the plumbing: provider integrations, recovery, run tracking and learning are all here. Run it on your laptop with one command, in one container, or as a server with runners. Apache-2.0.

You need Node 24.22.3 or newer, on macOS or Linux.

1. Start it.

   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.

2. Add one model key. In the console, set a password, then add a key under Settings → Model keys. One OPENROUTER_API_KEY gives every harness a model. An Anthropic key runs pi and Claude Code; an OpenAI key runs pi, Codex and OpenCode.

3. Run your first agent. Open Templates, apply KYB due diligence, and start a run with a company's name and website. It needs nothing but your model key. When it finishes, the run's Report tab has a due diligence report with a verdict and every claim cited. Then open the agent's Learning tab to see what it kept for next time.

Rather have your coding agent do it? Tell it: Read agentrun.ai/SKILL.md and set up AgentRun for me.

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

• Notes are short markdown files, one fact each, in Claude Code's memory format.
• Skills are how to do a job again, and only a run that finished the job can write one.
• Learned workflows run as one tool call on any harness, under the run's own cap and tool permissions. Once a learned skill has served 3 runs, the next run is asked for that job as a workflow draft, and a draft is dry-run before it's kept: no model is asked and no tool runs.

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.

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:

{
  "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 }
  ] }
}

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.

• Approvals. Each tool is allowed, asks you first, or is denied. A call that asks waits on the run's page until you answer. "Never ask" lets an agent run unattended, and a deny set on the server still holds over it.
• Spend caps. Give a run a cap and it pauses there instead of failing, and tells you the least it needs to go on. A cost AgentRun can't price reads "unknown", never $0.
• Questions. An agent can stop and ask you, and the run waits until you answer.
• One console. Each run has a live Timeline, its files and, for a browser, a screen you can take over.

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.

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.

Triggers start capped runs on their own: schedules, signed webhooks and GitHub pull request events.

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.

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)

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.

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"]

• Server. Serves the API at /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.
• Store. Agents, revisions, runs and every run's journal, in one place. SQLite in the data folder by default, or Postgres with AGENTRUN_STORE_URL.
• Runners. Each runner claims runs from the store and runs many at once. Every approval check, cap and model call happens here. Add runners to scale out.
• Hands. Where the agent's tools act. Each run has a run folder for its files. A sandbox mounts that folder at /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.

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);

Render, in one click.

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. In Render's form, paste OPENROUTER_API_KEY. We recommend an OpenRouter key with a dollar cap and an expiration date. Do not share this key with anyone. When it's live, open its URL and paste AGENTRUN_TOKEN from the service's Environment tab to set your password.

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
echo 'OPENROUTER_API_KEY=...' >> .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

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.

• AgentRun Server: the API, models, tools, MCP servers, triggers, spend caps, learning and safety, in full
• Quickstart on agentrun.ai and the docs
• The CLI's skill and every command
• Deploying, computers, templates
• The workflow language, authoring, the guide
• Changelog and contributing

• A computer chosen per call, not only per agent
• First-party computers
• iPhone, macOS and Windows computers
• Watching and taking over a desktop or phone run, as a browser run does today
• Composio as a tool catalog
• Harnesses over the Agent Client Protocol
• A Slack trigger and a Parallel monitor trigger

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.