Repository navigation
AgentRun v0.1.0-beta.45
Pre-releaseThis release runs each run in a process of its own. In the Docker image each run is also a user of its own, so its tools can't read another run's folder or the store. A local install runs every run as the user who started the server. The image now starts the server and its runner as two processes, and run lists read one row per run, so a list costs the same at ten runs and at thousands. Learning comes down to two things an agent keeps: its owner's corrections and its compiled workflow. Computers without an Archil mount hold a run's folder as a synced folder, a Linux box of your own pairs as a computer, and a dial computer can be a desktop. Claude Agent can run on Claude Code's own login on a server one person runs, install.sh --vps sets AgentRun up on a rented Linux server, an agent another system owns can be deleted, a template can update the agent it made, and a run's page has a Dev tools tab with the run's trace.
Upgrading and going back:
- Back up the data folder (and the Postgres schema, if you use one) before you upgrade: the first start moves the store to SQLite version 13 or Postgres migration 0019, which beta.44 refuses, so going back means restoring that backup (#3123, #3133, #3170).
- The image now runs
server-and-runnerby default, the server and one runner as two processes. Under it a paired computer needs the server's options alone instead, and a computer that dials the server needs the server's public address inAGENTRUN_PUBLIC_URL(#3123, #3170). - Start the server before any runner of its own: a runner refuses a version 11 or 12 store until the server has upgraded it. After the upgrade the server builds each run's listing in the background, the runs no runner holds first (#3123).
- Each run now runs as a process of its own, and in the image as a user of its own: slot
sof a runner runs as uid and gid1001 + s, so a run's tools can't read another run's folder or the store.GET /v2/capabilitiessays which asrun_isolation("uid"or"process"). A local install runs each run as a process of its own under the user who started the server (#3128). - A learning run, an SDK backend run and a native run stay in the runner's process (#3128).
- In the image, the runner starts runs through a helper that needs its file capabilities. On a platform that strips them, or that starts the container with no-new-privileges (Docker's
no-new-privileges:true, Kubernetes'allowPrivilegeEscalation: false), the runner claims no runs and says why: "This runner will not claim runs: it cannot start a run as a user of its own (...)". Allow them, or setAGENTRUN_RUN_USER=sameto run every run as the runner's own user, each still in a process of its own (#3128). - Where each run is a user of its own, a
claude-agentrun on Claude Code's login on this machine that has nomodel_keyof its own fails when it is claimed: "A run on Claude Code's login on this machine needs runs under the server's own user, and this runner runs each run as a user of its own: set AGENTRUN_RUN_USER=same, or give the run a model_key." SetAGENTRUN_RUN_USER=sameon that server, or send the run amodel_key(#3124, #3128). - A run that brings its own
model_keyruns on that key alone: its runner opens it and hands it to that run's process, and the run gets none of the server's model keys (#3128). - Runners in containers of their own on one data volume each take their own range of slots with
AGENTRUN_RUN_SLOT_FIRST(deploy/compose.yamlgives 0 and 128). A runner told to hold more runs at once than its range reaches refuses to start (#3128). - The data directory is now mode
0711and the store's files0600. The Railway template's start command sets its volume to0711(#3128). - Going back after runs ran on beta.45: restore the whole data folder from before the upgrade. A run's files that beta.45 wrote belong to that run's user, which beta.44's server can't read (#3128).
- Remove
--learning-budgetand--grade-modelfrom the server's start command: the server no longer takes them and won't start with them. An agent's notes and learned skills are no longer served; put what an agent should always follow into itscorrections.md, one-line each (#3097). - The Cloudflare relay's box image moved to this release's recipe (
ghcr.io/parcha-ai/agentrun-box:87f44537b8b7, which this release publishes). Redeploy the relay from beta.45 once the release is out to give Cloudflare computers the new box, desktops included.RELAY_VERSIONstays 1, so a relay from beta.44 keeps working (#3167).
Breaking:
- Image: the default command is
server-and-runner, andrender.yamland the Railway template run it too. An operator who gives the image server options of their own still gets one process with the runner inside it; putserver-and-runnerbefore them for two. On the default command a paired computer is refused, and so is a provider whose machines dial the server while the runner has no public address: every provider row and paired computer inGET /v2/computerscarriesruns_refused, null where runs can use it, and the console shows it (#3123, #3170). - Image: on a platform that strips file capabilities or sets no-new-privileges, the runner claims no runs until the platform allows them or
AGENTRUN_RUN_USER=sameis set. The Render and Railway templates setAGENTRUN_RUN_USER=same; a server already deployed from either and moved to this release needs that variable added in its environment, or its runner claims no runs (#3128). - Learning: notes, learned skills, the look-back turn and the learning grader are gone. Removed:
GET .../learning/notes,PUT .../learning/files/{file},POST .../learning/workflows/{name}/promote, the learning batches and evals, the server options--learning-budgetand--grade-model,capabilities.learning.grade_model, and a definition'slearning: "notes". A grade'sfeedbackround iscorrection(waslook_back); a run's learning carriescorrectionsandworkflows, notgiven,read,learned,pendingorverdict. The clients'learning.notesandlearning.writearelearning.correctionsandlearning.writeCorrections(Pythonwrite_corrections). A native target'scapabilities.notesandcapabilities.skillsare onecapabilities.learning(#3097). - Learning cost: a cost run has
digest,took_overandauditedin place oflearned_revision, and a replay run'snis null.GET /agents/{id}/learning'simpactsides arerunsandmedian_duration_sonly: read a run's cost before and after learning from the cost read'ssummary, and what learning costs a run frombill.learning_usd(#3166). @parcha/agentrun-computer:ARCHIL_MOUNT_LABELisMOUNT_LABEL;RecordedArchil,recordedArchilandreadArchilMountareRecordedFolder,recordedFolderandreadMount;syncingClient(client, sync)takes the sync it runs,archilSync(client)for an Archil mount (#3118).- Tool keys:
GET /v2/settings/tool-keys(listToolKeys) names a key row's harnesses by harness id:items[].harnessesis an array of strings, no longer only the four built-in names, since a harness its owner installs (goose) is named there once it is installed. The TypeScript and Python clients and the console saystring[]; a caller that switched overpi,claude-agent,codexandopencodehandles any other id too. (#3176) GET /v2/agents/{id}/learning: each workflow'sstatusis nowserving,checking,heldorstopped(the stateGET .../learning/promotionsgives it), elsependingorretired.activeis gone: a reader that testedstatus === "active"for a workflow given to runs tests that it is neitherpendingnorretired(#3179).
Known issues:
- Upgrading an existing Render or Railway server without
AGENTRUN_RUN_USER=samestops the container (it restarts in a loop) instead of refusing runs. Add the variable before you upgrade. beta.46 makes it refuse as described. - Under the image's default command, no run can use a paired computer. Start the image with the server's options alone for one.
- A runner of its own started on a Postgres store before its server has upgraded it says to start on a new, empty data folder. Don't: start the server first, which upgrades the store in place, then the runner.
- A learned workflow refused for a host setting (a tool gated, denied or missing) still reads
serving, while every run it is given hands back to the agent. A workflow this release's DSL refuses is held, as in beta.44. - For up to about 10 minutes after the release is published, an install can fail while npm shows the new packages one by one. Try again a few minutes later.
- An API token's
GET /v2/settings/calendaris refused 403 in the words for saving a secret. Reading the calendar's settings takes the owner's signed-in session in the console, as saving them does.
Changes:
Runs and the server
- Each run is a process of its own under its runner, and in the image a user of its own. The run's process gets its own keys on a pipe and talks to its runner over a channel; the seal key, the API token and the store's address stay in the runner. What a run is handed is bound to its claim: a GitHub token only for its own pull request's repository, read-only, and decision and tier model keys only for the learned workflows its runner chose for it. When a run ends, every process of its user is stopped and its files in the shared temporary folders are removed. A learning run, an SDK backend run and a native run stay in the runner's process. (#3128)
GET /v2/runsand an agent's runs read each run's listing from its row: the status filter, the order, the limit and the cursor are one query, so a list costs the same at 10 runs and at thousands, however long their journals. Each item is whatGET /v2/runs/{id}gives for the run, as before. The image runs the server and one runner as two processes (server-and-runner), so a busy runner's journal writes no longer hold up the API's reads;docker stopreaches both, and if either exits, the other stops and the container exits non-zero. (#3123)- A run's trace:
GET /v2/runs/{id}/traceserves each model request and each tool call of a run as one span, with tokens, cost and timing, and the run page's new Dev tools tab shows it on one time axis and in one table, with a Breakdown view of where the time and the money went. The clients haveruns.trace, and the CLIagentrun runs trace RUN_ID. (#3125, #3153) - The runner writes a warn line,
event=cap_hold_short, when a paid model request bills more input than the bound its spend-cap hold was priced on, the one way a cap can be passed. It carries ids and figures only. Billing, holds and refusals are unchanged (#3146). - A backend SDK run's end-of-run compile ask is held to the run's cap like every other paid step: one that would pass the cap is not sent, and its learning is dropped with "Skipped: no budget left in this run to write what it learned." (#3160).
- A held computer's run released before its owner started it always ends cancelled, its agent never run. Before, a release that reached the runner just as it took up the run was missed and the agent ran (#3172).
- A run a person stops reads stopped as soon as nothing in it is working, never
input_requiredwith nothing to answer; tool calls still waiting for approval read withdrawn (#3165). - A server started while the one it replaces is still closing its store waits for the store's lock (10 s by default) instead of exiting with "database is locked" (#3173).
- A learning pi run that compacted its context twice or more reads its stored cost on
GET /v2/runs/{id}and in the learning cost read, instead of a nullcost.usd(#3180). - A webhook try's bound can be set, under the 60 s claim a try holds its message by: the server's
webhookTimeoutMsoption (15 s by default, as before) andWebhooks'timeoutMs. A try cut by it says the bound it had (#3177).
Learning
- An agent learns two things now: its owner's corrections and its compiled workflow. Notes, learned skills, the end-of-run look-back turn and the learning grader are gone. An owner's words after a run (a grade's words, or a message after the job's first) become one line of the agent's
corrections.mdwith no model turn, and every run reads that file whole. Read and replace it withGETandPUT /v2/agents/{agent_id}/learning/corrections(CLIagentrun learning correctionsandwrite-corrections). A compiled workflow is committed once its checks and dry run pass; its one promotion check against the agent's own answers decides whether it serves. (#3097) - The Learning tab tells one story: one run numbering, one takeover (the run the server marks
took_over), one cheaper ratio, and one figure for what learning costs a run, the bill'slearning_usd. Answer times show to a tenth under 10 seconds, the levels and the bill's labels sit right of the plot, and the captions say compile turn and audit shadow run. (#3166) - The learning view says of each workflow whether it serves:
serving,checking(no promotion record yet),heldorstopped(a champion the cost rule stopped running first readsstopped, neverserving) (#3179).
Agents and templates
DELETE /v2/agents/{id}deletes an agent another system owns (one an inline run made withexternal), whole, and answers 204. The agent refuses new runs first, its runs and learning runs are cancelled, then its learning, triggers (and their registrations upstream), sign-ins, own computer, Archil disk, runs and revisions go, then the agent. Sending the DELETE again finishes the job after a crash. An agent made on the server itself is refused 409agent_not_external; shared things (MCP servers, sealed keys, paired computers, tokens, uploaded files) stay. The clients havedeleteAgent, and the CLIagentrun agents delete-agent. (#3051)- Applying a template again can update the agent it made:
POST /v2/templates/{name}/applytakesagent_idand writes a new revision of that agent, keeping its runs and its learning. Its triggers are matched by name: one it has is changed in place (a feed keeps the items it has seen, a webhook its secret, one turned off stays off), a new one is made, and one the package no longer lists is removed. A trigger the owner added, or one made before this release, is left alone; one of the same name that can't be changed in place refuses the update with 409name_taken. In the console, a template that already made an agent shows "Update " next to Apply. (#3133) - Composio: the picker reads a toolkit's actions at its latest version (it used to miss the actions added since the base version), and a save refuses an action Composio doesn't list, 422
input_invalidnaming each slug, before anything is made at Composio (#3161).
Models and harnesses
- Claude Agent can run on Claude Code's own login on the same machine, on a self-hosted server one person runs:
PUT /v2/settings/claude-loginwithonly_me: true, or the console's Settings → Model keys row "Use Claude Code's login on this machine". The CLI keeps the login and calls Anthropic itself; AgentRun only asks itclaude auth statusand never reads, stores or relays the login. A run on it books its tokens and no dollars (cost.plan.on: "claude_code"). A server where more than one person can start runs refuses the mode, it is off by default on a server that listens beyond loopback, andAGENTRUN_CLAUDE_CODE_LOGIN=offremoves it. (#3124, #3126) - Particle-1 runs directly on Particle's own API with pi:
particle/particle-1andPARTICLE_API_KEY, in Settings → Model keys and the model picker, for pi runs and workflow model nodes. Costs are list-price estimates; the OpenRouter route stays as it was. The Compose files passPARTICLE_API_KEYthrough (#3149). - Goose 1.59.2 is a harness (
goose) on the ACP adapter (gooseAdapter), on the server's Anthropic key asclaude-agentis, with each Goose process on a model proxy of its own, so the run's cap and books hold as they do for Claude Code. Its owner installs it withagentrun harness install goose(agentrun-serve install-harness goose), never a run: the install checks the pinned archive's and the binary's sha256, puts the binary in place read-only, and names each failure with the command to try again. Restart AgentRun after installing it; until then an agent on goose saves with a warning and its runs are refused, namingHARNESS_NOT_INSTALLEDand the install command. (#3150, #3176) In the image only; an npm install has no Goose until its adapter package is published. - The console's API playground names an agent's model with the agent editor's Model picker, for the form's harness (#3164).
Computers
- A computer can take a synced folder,
mount: { kind: "sync" }: a plain/workspacethe runner fills and reads back over the computer's own file and exec calls, with no FUSE. Every provider configuration with files and exec takes it. (#3118) - In Mode 2, a sandbox or desktop whose provider takes no Archil mount here, or whose image has no Archil client, holds the run's folder as a synced folder instead of being refused: hosted Daytona, a Daytona sandbox with an egress but no snapshot, Daytona's and Modal's GPU computers, and a provider whose machines dial the server. The folder stays on the run's Archil disk, is pushed into
/workspacewhen the run is claimed, and each change lands on the disk before the call that made it answers. A folder over 20000 entries or 2 GiB is refused before anything is rented. (#3168) - A synced folder keeps its links and modes when a run moves off an Archil mount, and a runner that lost a run's claim can no longer write its folder: "this runner no longer holds the run's claim, so its write to the run's folder was not sent". (#3175)
- A Linux box of your own pairs as a computer:
computerd pair <server URL> [--name <name>]reads the console's code from stdin and keeps the token in~/.config/agentrun/computer.token(root's in/etc/agentrun/), mode0600, never printed;computerd attachreads it, andcomputerd unpairdeletes it. A box with a display pairs as a desktop. A paired computer that says hello with another arch than it paired with is closed4400. (#3174) - A dial computer can be a desktop on E2B, Fly Machines, Cloudflare, Modal and Daytona: the box image's
agentrun-dialstarts its display, and until it answers the computer is a linux one whose screen and input calls are refused in words. The box image's recipe changed, so its name moved with its hash. (#3167) - A computer whose machines dial the server (Fly Machines, Cloudflare, and E2B, Daytona or Modal set to dial) works under a runner in a process of its own, the image's default included: the machine dials the server as before, and the server relays its socket to the runner that made it. Give the runner the server's public address,
AGENTRUN_PUBLIC_URL(the image passes the environment to both); across hosts, also itsAGENTRUN_RUNNER_LIVE_HOST, listed in the server'sAGENTRUN_RUNNER_HOSTS. A dial whose runner is gone or restarted is answered 503 in words naming its run, and the run makes a new machine at its next claim. A runner started beside its server in the image no longer gets the server's own API tokens. (#3170) - The server and the runner make every computer provider's vendor call through the standard
HTTPS_PROXY(orHTTP_PROXY), withNO_PROXY's hosts, loopback and the server's own public address direct. Unset, nothing changes. The Archil mount still connects direct. (#3157) - A Linux box with no display pairs with
computerd pairas a sandbox, and in Mode 2 holds a run's folder as a synced folder in its/workspace; the next run on the box finds its folder. Its network isopen(#3178). - An API-only server (
AGENTRUN_API_ONLY=1) servesGET /v2/computersandGET /v2/workspace/archilwith its token, so a backend in front of it can read which computer providers are ready and whether runs' folders are on Archil. Both name keys and whether each is saved, never a value; their writes stay refused there (#3184).
Setup
curl -fsSL https://agentrun.ai/install | sh -s -- --vpssets AgentRun up on a Linux server you rent (Ubuntu or Debian, as root), running the release's image with Docker Compose in/opt/agentrun, with Docker sandboxes for its agents' shell. It installs Docker only where there is none, keeps/opt/agentrun/.env(mode 600) and yourcompose.override.yaml, and running it again upgrades. With Tailscale logged in it serves AgentRun on your Tailscale network only; without it, it listens on the server's loopback and prints the steps to add Tailscale.--publiclistens on every address over plain HTTP, after saying what that exposes. (#3158)agentrun service install --env KEY=VALUEgives the service a local model (AGENT_MODEL_BASE_URL,AGENT_MODEL_GATEWAY_IDS,AGENT_MODEL,AGENT_MODEL_PRICE), kept through restarts, upgrades and a later install; any other name is refused, so no key lands in a unit file. The setup prompt starts AgentRun with the installer, adds a local Ollama model with oneservice install --envline, and deploys to Railway with the template's button. (#3129)- The server README says a trusted proxy changes the sign-in limit's key, never who you are (#3162).
Console
- A link in a step's one-line preview reads as its words, and every picker in a console form is described by its field's note and error, so a screen reader says them (#3169).
Docs and release
- A node with an unknown key reads "unknown key(s) for an agent node" (it said "a agent"); the CLI's flag help and the command reference give a flag's whole first paragraph and write
*/*as itself. (#3110) - The changelog fold puts a breaking change under a Breaking: heading, and knows a fragment a section holds by its marker, not by its words. beta.44's changelogs on main now carry its seven late changes as its release page told them. (#3138, #3139)
- Tests: four flaky tests deleted and the four real bugs under them fixed; a computer-deps test takes its Docker answer from the test, not the CI host; CI's Postgres job keeps its database on tmpfs; and three CLI tests hold one claim each (#3165, #3171, #3177, #3183).
- The fake calendar answers and counts only its own paths, so a host process that polls loopback listeners no longer fails a test that counts the calendar's reads (#3181).
Install
- Server:
npx @parcha/agentrun-serve@0.1.0-beta.45; every@parcha/agentrun-*package of this release is 0.1.0-beta.45 on npm - Launcher and CLI:
npx @parcha/agentrun@0.4.13 - Python client:
pip install parcha-agentrun==0.3.13 - Server image:
docker pull ghcr.io/parcha-ai/agentrun-server:v0.1.0-beta.45(linux/amd64, linux/arm64)