What is AgentRun?
AgentRun is an open-source platform from Parcha Labs, Inc. for running AI agents on an existing agent harness. An agent keeps the harness it is defined on (pi, Claude Code, Codex or OpenCode), and AgentRun adds three layers around it: learning from completed runs, durable execution, and a control plane with approvals, spend caps and a web console. The official website describes it as open-source AI agent management from Parcha Labs, the makers of Grep.ai, and the repository README states that the code is copyright 2026 Parcha Labs, Inc. and built by Grep.ai.
The getting-started guide lists three ways to use it. AgentRun Cloud at console.agentrun.ai is operated by the Grep team. The local option starts with npx @parcha/agentrun on macOS or Linux with Node 24.22.3 or newer: it starts a server and one runner on port 7340 (or the next free port), keeps its data in ~/.agentrun and opens the console. Self-hosting uses a Render blueprint, the container image ghcr.io/parcha-ai/agentrun-server:beta or Docker Compose. The website lists a self-hosted plan that is free under Apache-2.0 with your own model keys, plus Cloud and Enterprise plans; it publishes no prices.
The platform itself is in public beta. Its changelog and the GitHub prereleases reach 0.1.0-beta.38 (November 14, 2026), and the npm launcher @parcha/agentrun is at 0.4.6. The latest GitHub release not marked as a prerelease is cli-v0.1.10 (November 6, 2026): the AgentRun observation CLI 0.1.10 with the Node launcher @parcha/agentrun-cli 0.1.1. That CLI connects selected Claude Code and Codex sessions to an AgentRun workspace and reports their activity; its release notes state that it does not execute or control agents and that the launcher supports Linux x64 with glibc and Node.js 20 or newer only. Beta 38 added a compile turn that writes a learning agent's whole job as a learned workflow, typed template parameters, MCP needs that name their source and toolkit, and a Linux desktop suite for the computer-use benchmark, and it lists known issues with Archil workspaces, Agent37 desktops and low Codex caps.
The architecture has four parts. The server serves the API at /v2 and the console. One store holds agents, revisions, runs and every run's journal: SQLite in the data folder by default, or Postgres through AGENTRUN_STORE_URL. Runners claim runs from the store, enforce approvals and caps, and make the model calls; more runners scale out. Hands are where tools act: a run folder plus an optional computer. AgentRun builds on pi by Earendil Works (MIT) for the agent loop and durable runtime, and on Stagehand, the Browserbase Node SDK and vercel-labs/durable-harness. Clients exist for TypeScript and Python.
The code is licensed under Apache-2.0; the website artwork lives in a separate private repository and is not covered by that license. The README's "Coming next" list names features that are not available yet, including a computer chosen per call, first-party computers, iPhone, macOS and Windows computers, taking over desktop and phone runs, harnesses over the Agent Client Protocol and a Slack trigger. Model usage and remote computers are billed by the respective vendors, not by the open-source platform. Similar projects in this directory: Omnigent, HarnessRouter, Omnara and Archon.
Key capabilities
- Four agent harnesses behind one API An agent definition names its harness:
pi(the default),claude-agentfor Claude Code,codexoropencode. Approvals, caps, computers, triggers and learning work the same on each, andnpx @parcha/agentrun server capabilitiesreports which harnesses a server can run. Claude Code and Codex install themselves on first use; OpenCode needs itsopencode-aipackage beside the server. - ChatGPT sign-in or model keys After setting a password, the console offers Continue with ChatGPT, which runs Codex and pi agents on the user's ChatGPT plan without an API key. Alternatively one
OPENROUTER_API_KEYgives every harness a model, an Anthropic key runs pi and Claude Code, and an OpenAI key runs pi, Codex and OpenCode. The documentation states that a ChatGPT sign-in is for the person who runs the server and is not to be shared. - Agents that learn from their runs With
"learning": true, an agent gets one more turn at the end of each run to propose what to keep: notes (one fact each, in Claude Code's memory format), skills, or learned workflows. AgentRun checks and grades each proposal and commits the accepted items to the agent's own git folder on a singlemainbranch. The Learning tab lists every item and its history, and an item can be retired there or withnpx @parcha/agentrun learning retire. - Checks on what an agent may learn Code checks every proposal before a grader sees it. An item that breaks a size, count, name or shape rule is dropped on its own, while a secret, a hidden character, a file outside the folder, a deletion or a full index drops the whole answer. A rule found in a fetched page or pasted email, or a note holding an account number, is dropped, and a risky rule waits for a person's approval.
- Learned workflows from a compile turn Since beta 38, a learning agent with 3 or more active notes or 5 or more completed runs can be asked to write its whole job as a workflow. The draft goes through static checks and a dry run in which no model is asked and no tool runs, with up to 3 more attempts after a refusal.
GET /runs/{id}/learningrecords each attempt and whether the workflow was promoted. - Typed workflow language Repeatable work can be written as a JSON workflow of typed steps: tool calls, model steps, fast typed decisions with a confidence (yes or no, pick one, a score), branches, parallel maps, bounded loops, calls to other workflows and hand-off of unclear cases to an agent.
npx @parcha/agentrun workflows validatechecks a workflow before it is saved as an agent'sworkflowfield. The workflow language also runs on its own inside an application, with a TypeScript builder. - Durable runs Every agent, revision, run and step lives in one store. A run continues after the server is stopped and started again, and with several runners another runner picks up a dead runner's runs once their 30-second lease expires. A finished step is never run again, and a write that a crash interrupted mid-call is marked interrupted instead of being retried.
- Approvals per tool Each tool is set to allowed, ask first or denied. A call that asks waits on the run's page until a person answers. A "Never ask" setting lets an agent run unattended, while a deny set on the server still applies over it.
- Spend caps and cost reporting A run can be given a cap, for example
--max-cost-usd 1; at the cap it pauses instead of failing and states the least it needs to continue. A cost that AgentRun cannot price is shown as "unknown", never as $0. The beta 38 changelog notes that a Codex run with a cap under about $2.50 can pause early. - Questions to a person With the
ask_persontool an agent can stop and ask a question, and the run waits for the answer. From the CLI,runs waitexits with 0 when a run completed, 1 when it failed and 8 when it waits on a person because of a question, its cap or an approval. - Mission Control console The console opens on Mission Control, which shows agents, runs, tokens, run time, success rate and cost per day, by harness and by tool, plus runs that need input or failed. Each run has a live Timeline, its files and, for a browser computer, a screen that a person can take over and hand back. Workflow runs are shown node by node and can be paused and resumed.
- Computers for agents One
computersetting gives an agent a kind of machine:none(file tools only),sandbox(Docker, Daytona, Modal or E2B),desktop(Orgo, E2B or a Docker image with an X server),phone(a rented cloud Android) orbrowser(Browserbase or Kernel). Without a setting, an agent gets the Docker sandbox where the server has Docker. Vendor keys are sealed on the server and never enter the agent's computer, and remote computers bill through the user's own vendor account. - Five templates with eval cases Ready-made agents are
code-review,kyb,market-monitor,inbound-leadandrelease-notes. Each is one folder with instructions, skills, rules and eval cases, and applying one grants no MCP tool until each is ticked.npx @parcha/agentrun template eval DIRruns a template's eval cases as real runs on a throwaway server and grades them. - Triggers Triggers start capped runs from schedules, signed webhooks, GitHub pull request events and Composio events. Template trigger inputs can take typed parameter values, so a list set at apply time reaches each run as a list.
- MCP servers and Composio Settings, MCP servers adds the tools of any remote MCP server to an agent. With a Composio API key, toolkits and individual actions can be loaded, connected to the user's account on Composio and ticked per agent. The Composio tutorial lists the API call for each step.
- HTTP API, Playground and clients Every agent is reachable over the
/v2API, and the Playground builds a run request in a form and shows the same request as cURL or JavaScript. The TypeScript client@parcha/agentrun-clienthas no dependencies. The Python clientparcha-agentrunis typed from the server's OpenAPI document, uses only the standard library and needs Python 3.10 or newer. - Command-line interface
npx @parcha/agentrunis also the server's CLI: it creates agents, starts and waits for runs, sends messages, streams a timeline withruns timeline RUN_ID --followand reads run files.npx @parcha/agentrun skill install --claudeor--codexinstalls a skill that teaches a coding agent the CLI. - Secret handling Saved secrets (model and tool keys, MCP credentials, sign-ins and webhook signing secrets) are sealed under one key,
AGENTRUN_SEAL_KEY, and losing that key loses what it sealed. Secrets are write-only: the console shows each one only as set or missing, and the API token can neither write a secret nor approve a tool call. A run receives only the keys its own model and tools need. - Self-hosting on Render, Docker or Postgres The Render button deploys one 1 CPU / 2 GB instance with a 10 GB disk from the published image; the README quotes about $25 a month for the instance and $2.50 for the disk at Render's prices when it was written. Docker Compose starts a server and two runners on a Linux machine, and runners can share a Postgres store with the server started as
--no-runner. The deployment guide covers runners, capacity, health checks and upgrades. - Observation CLI for existing sessions The separately released observation CLI (cli-v0.1.10) connects selected Claude Code and Codex sessions to an AgentRun workspace through device authentication or an enrollment credential. It reports activity and does not run or control agents. The launcher provisions Python 3.12, verifies release checksums and supports Linux x64 with glibc only.
Where AgentRun fits
Pull request review on a team's own repository
The code-review template 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 one and returns them as JSON. It sets up its own GitHub trigger, and its GitHub tools are pinned to the one repository. The project's code review case study reports a cost of 18 cents a review on a cheap model and 1.6 times the real bugs caught by Greptile on 30 unseen pull requests, and a separate tutorial describes tuning the template on another repository.
Company due diligence
The kyb template researches one company: registries, owners, sanctions lists and dated adverse media, ending in a verdict with every claim cited. It is the agent used in the local quickstart: after a run with a company name and website, the run's Report tab holds the due diligence report and the agent's Learning tab shows what it kept for the next run. The console screenshots also show a KYB onboarding workflow that routes a case to review when a typed decision falls under a 0.75 confidence rule.
Handing a learned job to a cheaper model
The project describes letting a strong model work out a task, then passing what it learned to a cheaper model. In its merchant classification case study, Opus learned how to classify merchants and a cheaper model then did the same job, with the reported cost going from $0.89 to $0.12 per merchant. The Learning tab shows the kept notes and the cost and latency since the agent learned.
Event-driven agents with Composio and GitHub
A Composio toolkit added under Settings, MCP servers can supply an agent's tools, and a webhook trigger with Composio's signature starts a capped run when a Composio event arrives, for example a new GitHub issue. The README walks through the five steps from loading a toolkit to watching the triggered run on its Timeline. Other templates use the same mechanism: market-monitor sends a dated Monday digest about watched companies, inbound-lead scores leads from a webhook from 0 to 100, and release-notes drafts notes from merged pull requests as an issue for a person.
Agents that use a computer
Agents that need a shell, a Linux desktop, an Android phone or a browser get one through the computer setting, with the provider chosen in Settings, Computers. A browser run streams to the run's Screen tab through the user's own server, and the agent can stop and ask a person to take over for a login or a captcha. Each provider has a conformance suite that can be run against the vendor from a checkout.
Starting runs from scripts and applications
The README includes a shell script that creates an agent with write and ask_person tools, starts a run capped at $1, answers the agent's question and reads the file it wrote, using exit code 8 to detect a waiting run. The same flow is shown with the TypeScript client, and the Python client offers the same methods. Every run carries a console_url to its page in the console.
Install
npx @parcha/agentrunReviews of AgentRun
Be the first to share your experience with AgentRun.
Write a review
Loading review form…
Found AgentRun useful? Upvote it todayYour vote helps other IT teams find it in the daily ranking.






