AgentRun: Open-Source Self-Improving Agents With Durable Runs and a Control Plane

AgentRun is an Apache-2.0 open-source platform from Parcha Labs that wraps an existing agent harness (pi, Claude Code, Codex or OpenCode) with three things: a learning loop that persists notes, skills and workflows between runs, durable execution backed by a single store, and a control plane for approvals, spend caps and monitoring. It is installed with npx @parcha/agentrun, runs on Node 24.22.3 or newer on macOS or Linux, and serves its console on port 7340 by default.

The problem AgentRun targets: agents re-derive the same work on every run

Agents repeatedly rediscover the same API, reread the same documentation and rebuild the same plan, and the operator pays for every token of that rediscovery. AgentRun's stated pitch is "Run smarter agents. Use fewer tokens." The project's own console screenshot shows an agent's Learning tab where, after learning, answers take 2 seconds instead of 10 and a run costs $0.0077 instead of $0.05. The README labels that figure as demo data from the console's recorded fixtures.

The design consequence is that AgentRun is not another agent loop. It sits around a harness the user already trusts and adds persistence, recovery and governance on top. The README describes the split explicitly: "Bring your agent on the harness it runs best on: Claude Code, Codex, OpenCode or pi. AgentRun does everything around it."

The self-improvement loop runs as an extra turn at the end of each run

Learning is opt-in per agent with "learning": true in the agent definition. At the end of every run the agent gets one additional turn to propose what it would keep. AgentRun then runs code checks, followed by a single grader, and commits whatever passes to the agent's own git folder. The next run starts from that state. The README's flowchart summarizes the cycle: run starts from the agent's main, the run does the job, a last turn proposes notes or a skill or a workflow, code checks and one grader run, kept items are committed to main.

There are three artifact types:

  • Notes are short markdown files holding one fact each, in Claude Code's memory format.
  • Skills describe how to do a job again; only a run that actually finished the job can write one.
  • Learned workflows execute as a single 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 to produce that job as a workflow draft, and the draft is dry-run before it is kept, with no model asked and no tool run during the dry run.

The agent's Learning tab lists every note, skill and workflow plus a change log, and each run records which notes it was given and which it opened. Items can be retired from the console or with npx @parcha/agentrun learning retire and the note's ETag. Because the folder is a git repository, a retired note can be restored from history.

Learning proposals are filtered by code before any model grades them

Each agent has a learning folder: plain git with one branch, main. Code checks every proposal first. An item that breaks a rule of its own, such as a size limit, a count limit, its name or its shape, is dropped individually and the rest of the proposal continues. Four failure conditions drop the entire proposal rather than one item: a secret or a hidden character anywhere in the answer, a file outside the folder, a deletion, or a full index. The README's rationale is that if any item cannot be trusted, none of it can. After the code checks, one grader judges content and AgentRun commits what passes.

Two categories are treated as risky. A risky rule waits for explicit operator approval. A rule sourced from a page or a pasted email, or a note that contains an account number, is dropped outright.

Index growth is handled with a retrieval step rather than by truncation: once an agent's notes outgrow the learning budget, each run receives the notes that bear on its first message in full, plus one line for each remaining note. A run that only executed a learned workflow is not asked what to keep.

Durable execution keeps a run alive across server restarts

Every agent, revision, run and step lives in one store. Stopping the server mid-run and starting it again allows the run to carry on. With multiple runners, another runner picks up a dead runner's runs once their 30-second lease expires. A finished step is never executed twice. A write that a crash cut off mid-call is marked interrupted rather than retried, so a human can inspect it.

The store is SQLite in the data folder by default, or Postgres when AGENTRUN_STORE_URL is set to a postgres:// URL.

Spend caps pause rather than fail, and unpriced costs are never reported as zero

A run given a cap pauses at that cap instead of failing, and reports the minimum it needs to continue. Any cost AgentRun cannot price is reported as "unknown", never as $0.

Tool permissions are per tool and take one of three states: allowed, ask first, or denied. A call that asks waits on the run's page until a person answers. "Never ask" mode lets an agent run unattended, but a deny set at the server level still applies over it. Agents can also stop and ask a question, and the run waits.

Workflows are for repeatable work; agents are the fallback

AgentRun's README argues that many agents do not need to be agents at all. Repeatable work can be expressed as a typed workflow: tool calls, model steps, and fast typed decisions (yes or no, pick one, a score, each carrying a confidence value), with an agent available as a fallback for unclear cases. Workflows run as an agent's revision, under that agent's tool permissions and cap, and can be started by a trigger.

A workflow is a JSON document of typed steps, versioned with "v": 2, with named schemas for input and output. The example in the README defines an In schema requiring a website string and a Page schema requiring an ok boolean, then chains a single tool step that fetches the home page:

{
  "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 a hard case to an agent. A workflow is saved as an agent's workflow field, and npx @parcha/agentrun workflows validate checks it first. The workflow language also runs standalone inside an application, with a TypeScript builder.

In the console a workflow can be watched node by node, paused and resumed, with every decision and its rationale visible.

Four harnesses, five kinds of computer

The harness is chosen per agent with the harness field.

Harness harness value Notes
pi pi The default
Claude Code claude-agent Installs itself on first use
Codex codex Installs itself on first use
OpenCode opencode Requires its opencode-ai package beside the server

Approvals, caps, computers, triggers and learning behave identically across harnesses. npx @parcha/agentrun server capabilities reports which harnesses a given server runs.

The computer is a single setting on the agent, and the agent receives only the tools for that kind of computer.

Kind Capability Providers
none Read and write files in the run folder, no shell (with Archil, commands run on Archil's exec) none needed
sandbox Run code, install packages, keep background processes, on Linux Docker, Daytona, Modal, E2B
desktop See a Linux screen, move the mouse, type Orgo, E2B, Docker with a custom X server image
phone Tap, swipe, type, open apps, read the screen on Android phone harness (rented cloud Android)
browser Browse the web, hand controls to a human at any point Browserbase, Kernel

An agent with no computer setting gets a Docker sandbox when the server has Docker, and no computer otherwise. Remote computers bill through the operator's own vendor account.

Three operational details matter for teams deploying this. Vendor keys are added once in Settings, sealed by the server, and never enter the agent's computer. Run folders live on the server and are mounted by a Docker sandbox; enabling an Archil disk moves the folder there so Daytona, Modal or E2B sandboxes mount the same folder, and those three providers require an Archil disk while Archil on the Docker sandbox is refused. Browser runs stream to the run's Screen tab through the operator's own server rather than a vendor link, so control can be taken and handed back, and an agent can request a human takeover for a login or captcha.

Each provider has a conformance suite runnable against the vendor: npm run conformance -w @parcha/agentrun-computer -- --provider docker --kind sandbox.

Five ready-made templates ship with it

Template What it does
code-review Reviews a pull request or diff, checks each finding against the code, returns findings as JSON, 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 A Monday digest of what changed at watched companies, each item dated and linked
inbound-lead Researches each webhook-delivered lead and scores it 0 to 100 against an ideal customer profile
release-notes Turns merged pull requests since the last release into release notes, left as a draft issue for a person

Applying a template grants no MCP tool access until each tool is ticked manually. npx @parcha/agentrun template eval DIR runs a template's eval cases as real runs on a throwaway server and grades them. Triggers start capped runs on their own from schedules, signed webhooks and GitHub pull request events.

Architecture: server, store, runners and hands

The server serves the API at /v2 plus the console, writes runs and commands to the store, and reads them back. Started with --no-runner, it runs no agent loop itself. Runners claim runs from the store and execute many concurrently; every approval check, cap and model call happens in the runner. Hands are where the agent's tools act: each run has a run folder, and a sandbox mounts that folder at /workspace while a desktop, phone or browser leaves the folder on the runner.

Scripting: CLI, TypeScript and Python clients

npx @parcha/agentrun doubles as the server's CLI; run against a live server it discovers the address and token automatically. Exit codes from runs wait are 0 for completed, 1 for failed, and 8 for waiting on a person: a question, a cap, or an approval. runs timeline RUN_ID --follow streams each step, and every run carries a console_url.

The TypeScript client is @parcha/agentrun-client (no dependencies) and reads AGENTRUN_BASE_URL and AGENTRUN_API_KEY from the environment. The Python client is pip install parcha-agentrun and exposes the same methods.

import { AgentRun } from "@parcha/agentrun-client";

const client = new AgentRun();
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);

A convenience path for coding-agent users: instruct the coding agent to Read agentrun.ai/SKILL.md and set up AgentRun for me, or run npx @parcha/agentrun skill install --claude (or --codex) to teach it the CLI.

Deployment costs and topologies

A one-click Render deployment uses the repo's render.yaml: one 1 CPU / 2 GB instance with a 10 GB disk, the published image with no build step, and an auto-generated token and seal key. The README states that this costs about $25 a month for the instance and $2.50 for the disk at Render's prices when written, and requires a card on the Render workspace. The recommendation is an OpenRouter key with a dollar cap and an expiration date.

A Docker Compose deployment runs one server and two runners. Its published port is bound to the host's loopback only, so a TLS proxy is required before exposing it. That compose file has no Docker socket, meaning its agents get file tools and web_fetch but no shell; a Docker sandbox requires the root compose.yaml with Docker Engine 26 or later, running the server on the host, or a Daytona/E2B computer with an Archil disk.

For scale-out, set AGENTRUN_STORE_URL to a Postgres URL on the server and every runner, start the server with --no-runner, and start each runner from the same image with runner --data /data --name <name>. All processes must share the same AGENTRUN_SEAL_KEY. In the documented release, runners still share the /data volume.

Security model: one seal key, write-only secrets, a limited API token

Every saved secret (model keys, tool keys, MCP credentials, sign-ins, webhook signing secrets) is sealed under a single key, AGENTRUN_SEAL_KEY, whose loss means the loss of everything it sealed. Secrets are write-only: the console shows each as set or missing, and only the console can paste, replace or remove one. A key present in the server's environment wins over a pasted key. The API token cannot write a secret or approve a tool call. A run receives only the keys its own model and tools need, and nothing a run learns can retain a secret it was handed.

What the Hacker News thread pushed back on

The Show HN post reached 134 points and 39 comments. The thread's substantive questions targeted the learning loop, cost accounting and differentiation; the captured comments do not include maintainer replies to them. Several comments in the thread were flagged or dead, and several others were vendor self-promotion, so the technical signal is concentrated in a small number of threads.

The single most-asked question was how self-improvement actually works:

Could you explain how the self-improving part works?

The sharpest cost-accounting challenge concerned whether spend caps can actually be enforced when agents can spawn detached work:

I've noticed on some of my own research and testing that even with caps some agents will work around the per-call time limit using background processes. Do your caps cover compute in the detached processes?

A related architectural question asked whether AgentRun uses an existing harness or bypasses it, motivated by subscription economics:

Do it uses the claude code harness (for example) or bypass it? I ask because of the subscription.

A commenter with a hand-built orchestrator, featuring an executive agent that chunks work, builds a dependency graph, assigns recursive sub-agents and runs an independent reviewer per chunk, asked what AgentRun adds:

So what would your thing give me that mine can't do?

The most detailed critique enumerated four operational worries about persisting learnings as notes, skills and memory:

  1. How do you ensure the learnings necessarily apply? 1. How do you ensure learnings are deterministic? 2. How do you prove that the outcome of the learning's enforcement yields what you actually want? 3. As more learnings are piled on, how do you manage costs and latency?

Read against the README, several of these map onto features the project already specifies: retrieval of notes by relevance to the run's first message addresses applicability, the code-check-then-grade pipeline plus human approval for risky rules addresses correctness, dry-run-before-keep for learned workflows addresses determinism of promoted artifacts, and the learning budget with per-note index lines addresses index growth. The README does not make a determinism guarantee for notes or skills, and it does not describe spend-cap enforcement over detached processes inside a sandbox.

The thread also drifted into adjacent debates

Two vendor founders used the thread to argue about neighboring concerns. The CEO of Sourcery framed AI code review as a precision-recall trade-off, taking the recall side:

We believe that outputting a lot of comments, even if they're nitpicky, is the right way to go for coding agents because they can triage all of the comments very rapidly and decide which to address and which are not relevant.

He also claimed that over 80% of Greptile's review comments get addressed on GitHub, with Sourcery producing over 2x as many comments as Greptile and the example under discussion producing 1.6x. Separately, the CEO of Kubit raised the observability question of detecting when production runs diverge from a compiled workflow, noting that his product groups runs by execution path after labeling every span so new branches surface quickly. A commenter from SavvyIQ offered roughly 200 government registrar integrations and 500 million entities as a potential data source for the KYB template. Another pointed at a local orchestrator for subscription-based PR review, and one asked the broader question of how teams handle PR volume in 2026, floating SLSA attestations for build provenance.

None of these are core to AgentRun's design, but they indicate where practitioners see the gaps: reviewer precision versus volume, drift detection once workflows are compiled, and third-party data coverage.

What the project lists as coming next

The README's roadmap names: a computer chosen per call rather than only per agent; first-party computers; iPhone, macOS and Windows computers; watching and taking over desktop or phone runs as browser runs already allow; Composio as a tool catalog; harnesses over the Agent Client Protocol; and a Slack trigger plus a Parallel monitor trigger.

What AgentRun actually is, in one paragraph

AgentRun is a durable, governed runtime around an existing coding-agent harness, with a persisted learning layer that stores one-fact notes, reusable skills and compiled workflows in per-agent git repositories. Its distinguishing claims are that learning proposals are machine-checked and graded before commit, that runs survive server restarts through a single SQLite or Postgres store with step-level idempotency, and that every run is bounded by approvals and spend caps. It is Apache-2.0, copyrighted 2026 by Parcha Labs, Inc., built by Grep.ai, and it builds on pi by Earendil Works (MIT), Stagehand and the Browserbase Node SDK, the TypeSafe JavaScript SDK, Archil's disk SDK, and vercel-labs/durable-harness (Apache-2.0).

Sources

Related

  • Project
  • Project
  • Project
  • Project
  • Dispatch