Show HN: AgentRun – open-source, Self-improving Managed Agents

Run smarter agents. Use small tokens.

Quickstart · Tour · Templates · Deploy · Docs

AgentRun is an open-source phase that supercharges your agents. It adds self-improvement, durable implementation and a control aircraft on top of your favorite delegate harness. Your agents rotate into smarter, additional error tolerant and use fewer tokens alongside all run.

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

Agents are awesome at figuring things out. The issue is they fig out the identical things complete and over. Give an agent a job it has done a hundred times and it rediscovers the identical API, rereads the identical docs and rebuilds the identical plan, and you pay for all token of it.

Bring your delegate on the harness it runs finest on: Claude Code, Codex, OpenCode or pi. AgentRun does everything about it:

• It learns the work. After all run, the delegate keeps what volition assistance 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, commencement it again, and the run carries on. Give all delegate the device the job needs: a sandbox, a Linux desktop, an Android phone or a browser.
• You remain in control. Approvals, expend caps and one console for all 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 alongside one command, in one container, or as a server alongside 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 harbor 7340 (or the next liberated one), keeps everything in ~/.agentrun, and opens the console in your browser.

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

3. Run your archetypal agent. Open Templates, use KYB due diligence, and commencement a run alongside a company's name and website. It needs nothing but your example key. When it finishes, the run's Report tab has a due diligence report with a verdict and all assertion cited. Then open the agent's Learning tab to see what it kept for next time.

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

If Docker is operating on your machine, new agents get a Docker sandbox alongside a shell. Its depiction builds on archetypal use, which takes a few minutes, and the console says whenever it's ready. Without Docker, agents motionless peruse and compose files, but get no shell.

Want your own server alongside a URL? Deploy it to Render in one click.

Workflows that create the call. A stage can ask a accelerated typed question, see how certain the answer is, and choice a route. Here the example leans endorse at 0.61, below the workflow's 0.75 bar, so the case goes to review.

Every delegate in one place. Mission Control opens first: what needs you, what failed, what's operating and what it cost, by day, by harness and by tool.

Every delegate is an API. Start a run from the Playground, afterward copy the identical petition into your code.

You remain in control. An delegate can halt and ask you, and the run waits until you answer.

Turn it on alongside "learning": true in an agent's definition. At the end of all run, the delegate gets one additional rotate 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"] activity --> propose["Last rotate proposes<br/>notes, a skill, a workflow"] propose --> check["Code checks,<br/>then one grader"] inspect -->|kept| commit["Commit to main"] commit --> start 

• Notes are abbreviated markdown files, one fact each, in Claude Code's recollection format.
• Skills are how to do a job again, and lone a run that completed the job can compose one.
• Learned workflows run as one tool call on any harness, under the run's own cap and tool permissions. Once a learned accomplishment has served 3 runs, the next run is asked for that job as a workflow draft, and a outline is dry-run before it's kept: no example is asked and no tool runs.

The agent's Learning tab shows all note, accomplishment and workflow and the log of changes, and all run shows which notes it was stated and opened. Retire item there, or alongside npx @parcha/agentrun learning quit and the note's ETag. Git keeps the history, so a former note can arrive back.

Each delegate has a learning folder: plain git alongside one branch, main. A run says the indicator of energetic notes in its instructions and gets the learned skills beside its own. Code checks all recommendation first. An item that breaks a regulation of its own (a size or figure limit, its name, its shape) is remaining out and the remainder goes on. A concealed or a hidden character anywhere in the answer, a document exterior the folder, a deletion or a complete indicator drops the entire answer, since no item of it can be trusted. Then one grader judges what it says, and AgentRun commits what passes. A risky regulation waits for your OK. A regulation the run established in a leaf or a pasted email, or a note that holds an document number, is dropped.

Once an agent's notes outgrow the learning budget, all run gets the ones that withstand on its archetypal message, whole, and a line for all of the rest. A run that lone ran a learned workflow isn't asked what to keep.

A lot of agents don't need to be agents. Write repeatable activity as a typed workflow: tool calls, example steps and fast typed decisions (yes or no, choice one, a score, all alongside its confidence), alongside an delegate to autumn rear on whenever a case is unclear. AgentRun runs it as an agent's revision, under the agent's tool permissions and a cap akin any run, and a trigger can commencement one.

_{An example of the authority stream in examples/support-answer.mjs, not a record of a example run.}

Watch any workflow run node by node, intermission it and resume it, and peruse all decision and why it was made:

A 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 residence 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 accelerated typed question, branch on the answer, map complete a catalog in parallel, iteration a bounded figure of times, call another workflows, or hand the difficult 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 inner your app, alongside a TypeScript builder.

Every agent, revision, run and stage lives in one store. Stop the server mid-run and commencement it again, and the run carries on. With multiple runners, another runner picks up a deceased runner's runs formerly their 30-second lease runs out. A finished step is never run again; a compose a collision cut off mid-call is marked interrupted fairly than retried, so you can inspect it.

• Approvals. Each tool is allowed, asks you first, or is denied. A call that asks waits on the run's leaf until you answer. "Never ask" lets an delegate run unattended, and a refuse set on the server motionless holds complete it.
• Spend caps. Give a run a cap and it pauses there alternatively of failing, and tells you the smallest it needs to go on. A disbursal AgentRun can't cost says "unknown", never $0.
• Questions. An delegate can halt and ask you, and the run waits until you answer.
• One console. Each run has a live Timeline, its records and, for a browser, a display you can obtain over.

Five ready-made agents. Apply one in one screen, create it yours, and measure it alongside 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 all MCP tool yourself.

npx @parcha/agentrun template eval DIR runs a template's eval cases as genuine runs on a throwaway server and grades them. Template packages has the directory format.

Triggers commencement capped runs on their own: schedules, signed webhooks and GitHub drag petition events.

Harnesses. Name one in the agent's definition alongside harness. Approvals, caps, computers, triggers and learning work the identical on each. npx @parcha/agentrun server capabilities says which harnesses your server runs.

Computers. An delegate gets a device alongside one setting. It gets the tools for that benevolent and nothing else, and changing the device changes nothing alternatively concerning the agent.

computer: kind: sandbox # none, sandbox, desktop, phone or browser provider: daytona # one you connected in Settings → Computers (none takes no provider)

Every benevolent but none names its provider. An delegate alongside no device environment gets the Docker sandbox anywhere the server has Docker, and no device otherwise. Remote computers invoice through your own document alongside the vendor.

• Keys. Add a vendor's key formerly in Settings → Computers. Your server seals it and shows it lone as set or missing; it never enters the agent's computer. Test connection makes one peruse at the vendor and starts nothing.
• The run's files. By default a run's directory lives on your server and the Docker sandbox mounts it. Turn on an Archil disk in Settings and the directory lives there instead, so a Daytona, Modal or E2B sandbox mounts the identical folder. Those three run lone alongside an Archil disk, and alongside Archil on the Docker sandbox is refused.
• Watching and taking over. A browser run streams to the run's Screen tab through your own server, never through a vendor link. Take the controls, afterward hand them back. The delegate can additionally halt and ask you to obtain over, for a login or a captcha.
• Proof. Each provider has a conformance suite for its kind. Run it against the vendor yourself, from a checkout after 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.

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 directory + computer"] 

• Server. Serves the API at /v2 and the console. It writes runs and commands to the shop and says it rear for you. It runs no delegate iteration itself whenever you commencement it alongside --no-runner.
• Store. Agents, revisions, runs and all run's journal, in one place. SQLite in the data directory by default, or Postgres alongside AGENTRUN_STORE_URL.
• Runners. Each runner claims runs from the shop and runs many at once. Every endorsement check, cap and example call happens here. Add runners to measure out.
• Hands. Where the agent's tools act. Each run has a run directory for its files. A sandbox mounts that directory at /workspace and the tools run inner it; a desktop, phone or browser leaves the directory on the runner.

npx @parcha/agentrun is additionally the server's CLI. Run these in a second terminal during the server is up; the CLI finds it and its token by itself. The manuscript makes an agent, starts a run capped at $1, lets the delegate ask you a question, answers it, and says the document the delegate wrote. With Docker on, the archetypal run waits for the sandbox image.

# 1. Make an delegate that can compose records and ask you things. cat > agent.json <<'EOF' {"definition": {"id": "notes", "version": 1, "name": "Notes",  "instructions": "Do what you are asked, and compose what you create 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 area (exit code 8: it waits on you). npx @parcha/agentrun runs commencement notes --max-cost-usd 1 --wait \ --body '{"input": {"content": "Ask me which area to cover, afterward compose region.md concerning it."}}' > out.json # 3. Answer, delay for it to finish, and peruse what it wrote. run=$(node -p 'require("./out.json").run_id') npx @parcha/agentrun runs communication "$run" --content "Europe" npx @parcha/agentrun runs wait "$run" > out.json npx @parcha/agentrun runs read-file "$run" region.md

runs delay exits 0 whenever the run completed, 1 whenever it failed, and 8 whenever it waits on you: a question, its cap, or an approval. runs timeline RUN_ID --follow streams all stage as it happens, and all run carries a console_url to its page. npx @parcha/agentrun assistance lists all command; npx @parcha/agentrun accomplishment instal --claude (or --codex) teaches your coding delegate the CLI.

With the TypeScript client (npm instal @parcha/agentrun-client, no dependencies). The client says its server and token from the environment; the server prints the two whenever it starts (with npx @parcha/agentrun, the token is in ~/.agentrun/.token, and the location 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 area to cover, afterward compose region.md concerning 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 instal parcha-agentrun, alongside the identical methods (TypeScript client, Python client).

Render, in one click.

The clasp deploys render.yaml: one 1 CPU / 2 GB case alongside a 10 GB disk, the published depiction (no build), and the token and seal key generated for you. It needs a cardstock on your Render workspace: concerning $25 a duration for the case and $2.50 for the disk, at Render's prices whenever this was written. In Render's form, paste OPENROUTER_API_KEY. We propose an OpenRouter key alongside a dollar cap and an expiration date. Do not portion 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.

On a Linux device alongside Docker:

git copy 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 create up -d --build docker create logs server # the console's link, the archetypal visit's setup code and, the archetypal time, the token

The harbor is published on this machine's loopback only; put a TLS proxy in forefront before you open it to anyone else. This create document has no Docker socket, so its agents get document tools and web_fetch but no shell. For a Docker sandbox, use the single-server compose.yaml at the repository's base (Docker Engine 26 or later), run the server on the host, or use a Daytona or E2B device alongside an Archil disk.

Set AGENTRUN_STORE_URL to a postgres:// URL on the server and all runner (the create file's pg overview runs one), commencement the server alongside --no-runner, and commencement all runner from the identical depiction with runner --data /data --name <name>. Give all procedure the identical AGENTRUN_SEAL_KEY. Runners motionless portion the /data volume in this release.

Deploying AgentRun covers runners, health checks and upgrades.

Every saved concealed (model and tool keys, MCP credentials, sign-ins, webhook signing secrets) is sealed under one key, AGENTRUN_SEAL_KEY; keep it, since losing it loses what it sealed. Secrets are write-only: the console shows each one as set or missing, and lone the console can paste, substitute or eliminate one (your signed-in session, or the launcher's console on loopback whenever accounts are off). A key set anywhere the server starts wins complete a pasted one. The API token can't compose a concealed or endorse a tool call. A run gets lone the keys its own example and tools need, and nothing a run learns can keep a concealed it was handed. SECURITY.md says how to study a vulnerability.

• AgentRun Server: the API, models, tools, MCP servers, triggers, expend 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 device chosen per call, not lone per agent
• First-party computers
• iPhone, macOS and Windows computers
• Watching and taking complete a desktop or phone run, as a browser run does today
• Composio as a tool catalog
• Harnesses complete the Agent Client Protocol
• A Slack trigger and a Parallel detect trigger

Apache-2.0. Copyright 2026 Parcha Labs, Inc. Built by Grep.ai.

AgentRun builds on pi by Earendil Works (MIT), the delegate iteration 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; all package's NOTICE lists what it carries.