Repository navigation
AgentRun v0.1.0-beta.47
Pre-releaseThis release publishes the ACP harness package, so a server installed from npm offers Goose and Cursor once their pinned release is installed (agentrun harness install goose or cursor), and any ACP agent can be brought in as a recipe. AgentRun Server gets a Helm chart published with each release and Coolify and Dokploy templates. An ended run reads its booked cost instead of null, a compacted pi run reads its priced cost, and a run's cost carries its tokens, how its figure was reached and what its paid tool calls cost. A Composio server can act as each run's own account and price its calls, a model gateway is saved from the console, run notices post to Slack, agentrun doctor checks a setup, and a server whose runners all refuse to claim says so instead of queueing runs for good. The store moves on Postgres (migration 0020) and changes a table on SQLite: back up before you upgrade, since going back to beta.46 is that backup.
Upgrading and going back:
- The store moves: Postgres migration
0020_runners.sqlrenames the runners' relay tablerunner_relaystorunnersin place, keeping its rows. beta.46 refuses a Postgres schema at migration 20 ("set up by a later release than this one"), so going back on Postgres is a backup of the schema taken before the upgrade. SQLite stays at version 13: the server's start dropsrunner_relaysand makesrunners, whose rows are heartbeats each runner writes again within 10 s. beta.46 opens such a data folder, but its runner in a process of its own with a public address (the image's default command withAGENTRUN_PUBLIC_URLset, or on Render) does not start, since the table it writes its relay to is gone. Back up the data folder or the Postgres schema before you upgrade; going back to beta.46 is that backup and the beta.46 image or package. From beta.44 or older, beta.45's notes hold first. - Start the server before any runner of its own. A runner started on a store this release's server has not opened yet stops with exit 3 on SQLite and Postgres alike: "The store in is behind this runner: start the server first, which upgrades the store in place, then the runner." The image's two processes start in that order. A beta.46 runner with a relay does not start against a store this release's server opened, so upgrade the runners with the server.
- At each start the server heals, in the background, the ended runs whose stored cost is unknown while their booking is priced: it writes the booked figure once, in place of the unknown, and logs one
cost_healline with counts and no ids. A stored figure is never written over. The healed figures stay if you go back. - The server now sends anonymous usage counts, as docs/telemetry.md lists: a random id made for the data folder (kept in its
.telemetry.json), the version, the platform and how many runs ended there as a range, never prompts, files, keys, names, paths or addresses. The first start that can send prints a notice and sends nothing until its first heartbeat a day later.AGENTRUN_TELEMETRY=0orDO_NOT_TRACK=1where the server starts turns it off; it is already off in CI, under a test runner and under--faux(#3191). - A run-list row a beta.46 or earlier server cached is not rebuilt for the new
pathandworkflowfields, soGET /v2/runsand an agent's runs list can show such a run without them until the run changes.GET /v2/runs/{run_id}has both (#3258).
Breaking:
- A run's read and each runs-list row carry one
pathandworkflow: { name, digest }(the learned workflow that served it, null on any other run). The learning cost read'sbilldropsbaselineandpromoted: readsummary.beforeandsummary.takeoverinstead (#3229). - Daytona no longer offers a desktop on any connect (none ever started: its sandboxes block the tool user's namespaces):
{ kind: "desktop", provider: "daytona" }is refused with the reason (#3245). @parcha/agentrun-harness-acpno longer records a binary's first-seen digest itself:fileDigestRecord,verifyFirstSeen,DigestRecordandACP_BINARY_DRIFTare gone. Pin the binary's sha256 and callverifyPinnedBinary, or install it withagentrun harness install --recipe(#3238).agentrun nativetakes only the flags it names:--base-url(use--url) and--jsonare refused, exit 2 (#3225).- A run's cost
basisreadsreported,estimateorunpriced, no longer alwaysestimate; a run with no model request readsunpriced(#3145). - A refusal's words changed where a client may have matched them: a secret write refused to the API token ends with a console link (match the sentence it starts with), and a refusal a start-time switch causes names the switch (match the error code, which is unchanged) (#3137, #3132).
Known issues:
- Under the image's default command, no run can use a paired computer, a paired Linux sandbox included. Start the image with the server's options alone for one.
- 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. - 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. - Fixed: a runner of its own started on a Postgres store before its server had upgraded it said to start on a new, empty data folder. It now says to start the server first, on SQLite and Postgres alike (#3205, #3227).
Changes:
Harnesses
@parcha/agentrun-harness-acp, the adapter that runs an Agent Client Protocol agent as a harness, is published with this release, after the kernel and before the server, and the server depends on it. A server installed from npm offers Goose once its owner installs Goose's pinned release (agentrun harness install goose, oragentrun-serve install-harness goose --data <dir>) and restarts it. Goose 1.59.2 is pinned for Linux x86_64 and Apple silicon Macs, and its model requests go through AgentRun's model proxy under the run's cap (#3195).- Cursor runs as a harness (
cursor) over ACP, on its owner's own Cursor API key: install its pinned release withagentrun harness install cursor, setCURSOR_API_KEYwhere AgentRun starts, and restart. Each run is billed to your Cursor plan, with no spend cap of AgentRun's: it stops after 20 turns or 100 tool calls (AGENTRUN_CURSOR_MAX_TURNS,AGENTRUN_CURSOR_MAX_TOOL_CALLS). Cursor makes no file edits (every Write is denied in its CLI config), and its own shell commands and calls are asked of a person who can approve them and refused where no one can. The key goes to Cursor's runs alone and the credential Cursor derives from it is never written to disk. A model iscursor/<model-id>, checked against the models Cursor lists for the key. The release is pinned by its archive's, launcher's and every unpacked file's digest, for Linux x86_64 alone: on any other host, a Mac included, Cursor is refusedACP_BINARY_UNPINNED(#3238). - Bring your own harness, door 1: a recipe. A JSON file names an ACP agent's registry release (the archive's URL and sha256, the binary inside it), its billing (through AgentRun's model proxy, or the owner's plan with turn and tool-call limits), its literal env, files and session folders in a private HOME.
agentrun harness install --recipe FILEinstalls it, andagentrun harness-check --recipe FILE --model PROVIDER/MODELruns it for real: its own tools off, its environment an allowlist, the cap or plan limits, the pinned binary at every start, a kill and resume, a denied call, one of AgentRun's tools over MCP and a second runner, then writes a JSON report and prints theresume,tool_gateandbillingfacts. The loader refuses a recipe that breaks one of five rules by its code (RECIPE_KEY_NOT_OWN,RECIPE_BINARY_UNPINNED,RECIPE_PATH_OUTSIDE,RECIPE_INSTALLS_ITSELF,RECIPE_ENV_NOT_ALLOWLIST), and a binary that differs from the one its install recorded is refusedHARNESS_BINARY_MISMATCH. See docs/harness-recipe.md and HARNESS-SCORECARD.md, which rates 25 agents (#3231). - The ACP adapter ties Goose's tool title (
agentrun: <tool with spaces>) to AgentRun's tool, so the host's gate is asked once per call (#3249).harness-check's gate refuses every call that is the agent's own, so a call of AgentRun's tool the adapter can't tie failsmcp_toolinstead of passing, and itstools_offstage passes once the agent's first model request reached the provider; the adapter's and the model proxy's environment variables are one list (#3257, #3251).
Runs and the server
- A server whose runners all refuse to claim (their run isolation refused, such as an
AGENTRUN_RUN_USERthe runner does not know, or the image's helper unable to switch users on the platform) now says so instead of queueing runs forever. A start is 503runner_refusedwith the runner's words and their fix (set AGENTRUN_RUN_USER=same), a run already queued endsfailedwithrunner_refused,GET /v2/capabilitiescarries the words inrunner_refused, andGET /v2/healthanswers 200degradedwith itsrunnercheckrefused, so a platform's health check does not restart the service in a loop. A message to a run and a backend SDK run's start are refused the same way, and it all clears once a runner that can claim starts. Each runner keeps a row in the store saying it is there, judged on the store's clock, so a runner on another host whose clock drifts is no longer refused as not running. A server with--no-runnerand no runner yet still queues runs (#3239). - A run stopped while it waited on a person reads
input_required,idleand astoppedpending from the stop's answer to its end, where it briefly read working again (#3236). A follow-up to a Codex or Claude Code run stopped while a tool call ran is the run's next turn, not a turn after the stopped one is finished (#3228, #3242). - A command running when its sandbox is lost is no longer run a second time on the new one: the call fails with code
gone, saying the computer was lost and the call not run again, and the next call starts the new sandbox (#3202). A synced folder's replacement sandbox no longer puts the whole folder back on the run's disk; a run whose folder moves to an Archil mount loses the modes and links its synced claim recorded, and a kept synced computer whose keep lapses is deleted without a read-back (#3224). - Only a schedule trigger's run is handed its trigger's last result: a Composio, GitHub or webhook trigger's run no longer gets another event's answer (#3255, #3265). A schedule or any other trigger can start a connected agent's runs, uncapped, and refuses a
max_cost_usdon one (#3159). GET /v2/capabilitieslists the switches only the operator sets at the server's start (AGENTRUN_MCP_ALLOW_LOOPBACK,AGENTRUN_WEBHOOK_PRIVATE_TARGETS,AGENTRUN_BOX_ALLOW,AGENTRUN_BOX_CPUS,_MEMORY,_PIDS) underswitches, and a refusal one of them causes names the variable and the restart it takes.agentrun service install --envtakes the first two and keeps them (#3132).- The server remembers its public address and warns when a start changes it (
event=public_url_changed); a browser that opens the console at the old name is sent on to the new one with a 308, and the API's 403 names it (#3134). A server listening on every address prints its setup link at this machine's own IPv4 addresses too (#3152). agentrun import --help,native discover --help,reset-password --helpandrunner --helpprint that command's own usage and exit 0, andagentrun-serve <command> --helpdoes too (#3225, #3240).- The OpenAPI document requires what the server always sends (an agent's
kind,revision,revisionsandarchived_at, capabilities'harnesses), lists the 403 on the four secret writes that left it out, and hascomputer_unavailableinRunErrorCode; the TypeScript and Python clients' types follow (Python 0.3.15) (#3217, #3222, #3239).
Costs
- An ended run whose end stored its cost unknown, because its read of the booking failed or ran past its bound, reads the booked total on
GET /v2/runs/{id}and the runs list, no longercost.usd: null, and the store heals to it (see Upgrading). When the booking has nothing to read either, the cost says why in a new field,unknown: "booking_unread", and the console says "Unknown · cost not read" (#3259). - A pi run that compacted its context no longer reads its cost as unknown: the compaction's summary request is answered in the run's record, so the run, the runs list's live spend,
/usageand the run page read its priced total. The cap's own reading of a run's journal no longer counts that request twice (#3259). GET /v2/runs/{run_id}gainscost.tools_usd: the part ofcost.usdits paid tool calls cost (Monid, priced MCP tools, Parallel, browser time), never added to it (#3234).- A run's cost carries its model requests'
tokens(input,output,cache_read,cache_write,requests,unmetered) and abasisofreported(every priced request had the provider's or gateway's own figure),estimateorunpriced;GET /statsandGET /usagesay the same over the runs they sum, and the console shows the tokens beside the cost (#3145). - A pi run's model requests that answer at about the same time are each priced at their own cost, where one subagent's request took every sibling's booking; the run's total was right throughout. The model proxy takes an
x-agentrun-conversationheader naming a request's conversation, never sent to the provider (#3207). - An imported session its source did not price, such as a Codex session, reads at the model catalog's estimate the import kept, wherever a run's cost is shown (#3203).
Learning
- With no
learning.agree_on, a learned workflow's check and its shadow audit compare two answers by their decision through the agent's fast model (model_tiers.fast, elseAGENT_MODEL_FAST): one request at the replay's end, under the run's cap and booked as its spend. A reply that is not a verdict, a failed request or a cap refusal counts as a disagreement and says why; the check record keepsgraderand each disagreement'sdiffers_on. With no fast model the whole answer is compared as before (#3196). - A run a learned workflow served says so where runs are read:
workflowon the run and its runs-list row, "Learned workflow" in the console's Kind column and on its run page (#3199); a list row an earlier server cached waits for the run to change (see Upgrading).workflow.repick(found,missed, null) says whether a served run's answer re-picked after a quote miss, a composed workflow's own re-pick included, and its run page shows it (#3273, #3282). - The SDK compile prompt calls a learned workflow compiled and unchecked and no longer tells the agent to prefer it; the client's workflow context opens "Compiled workflows for this task (not checked):" (#3264).
- An existing eve 1.0.0 agent can connect through an additive extension that keeps its model, tools, permissions and durable execution, takes owner corrections and served workflows on later turns, and reuses checked workflows over approved read-only callbacks through a private local MCP bridge.
@parcha/agentrun-eveis held from publication while its integration is reviewed, so it is not on npm (#3121, #3254, #3261, #3269).
Tools and integrations
- A Composio preset server can act as each run's own Composio account: save it with
user_id: "per_run", and each run names its account inmcp_auth.<server>as{composio_user_id, connected_account_id?}on its start or message. The binding is sealed into the run's launch and erased at its end, never on the server's row, the run's view or a log line; a run that names none has its calls of that server refused unsent. A binding to the preset's default useragentrunis refused422(#3246, #3283). - The Composio save takes
price_usd, which prices every granted action at that amount a call, held under the run's cap and booked as its tool cost (before, every Composio call read $0), andauth_config_id, which uses an auth config you already have at Composio. A preset re-save keeps the prices set on the server (#3232). An action slug is at most 128 characters, and a guess is offered only for a case-only miss (#3220). - A model gateway can be saved in the console: Settings → Model keys → Use a model gateway takes a LiteLLM or other OpenAI-compatible proxy's address, its key, how it takes model ids and each tier's default, and Test lists its models. It takes effect with no restart;
AGENT_MODEL_BASE_URLset where AgentRun starts still wins. The API isGET,PUT,DELETE /v2/settings/model-gatewayandPOST /v2/settings/model-gateway/test, secret writes for the owner's signed-in session (#3144). - The server posts run notices to Slack itself: paste an incoming-webhook URL under Settings → Slack (
PUT /v2/settings/slack), and each run's end, wait on a person and failed trigger is posted with the agent's name, the status, the run's title and a link, never a run's input, output or a tool's arguments. Delivery is the outbound webhook's outbox, with deliveries, redelivery and a test send (#3143). - The outbound webhook's signing secret can be rotated for the same URL:
POST /v2/settings/webhook/secret, and Rotate secret in Settings → Webhook. The old secret is retired at once (#3136). - A secret write refused to the API token says where to finish it: the same
403 forbiddenends "Finish it in the console: ", with the link inerror.details.console_url, the console form filled with everything but the secret. The link never holds a token, a header or a key (#3137). - The README and the setup skill say how to run claude-agent through an Anthropic-compatible gateway with
ANTHROPIC_BASE_URL(#3141), anddocs/connect-tools.mdsays how to give an agent a service's tools without a token in its box (#3142).
Computers
- A run on a computer that mounts its folder attaches again when the run is a process of its own, as it is under every runner since beta.46: such a run was refused about 25 s in, saying the computer did not hold the run's folder (#3288).
- A smol cloud provider:
providerFor("smolcloud", { apiKey })makes each computer a smol cloud microVM booted from an OCI image, the box image by default, as a sandbox; Settings takesSMOLCLOUD_API_KEY. No mount and no desktop yet, and a synced folder's refusal says why (#3163, #3218). GET /v2/computerslists each kind'ssettings, which the console's Computer step reads (#3250). A dial desktop whose display is down failsconnectandwatchas drift, where it answered with no screen (#3250).- A Linux desktop waits 100 ms after a key action before the batch's next one, so an app acts on the shortcut first (#3215). A paired Linux box stays held until each remove and KILL its create sent has answered (#3214).
- The Fly, Cloudflare and Modal conformance modules take a kind (
COMPUTER_FLY_KIND,COMPUTER_CLOUDFLARE_KIND,COMPUTER_MODAL_KIND), dial conformance gives a desktop run the computerd fixture, andMACHINE_TOKEN_SOURCEgives a machine token's shape for a scrub (#3216, #3263).
Console
- The agent page says before Run what would refuse a run:
GET /v2/agents/{agent_id}carriesrun_blockers, and each shows as a warning (#3156). An agent's description is editable throughPUT /v2/agents/{agent_id}/definitionand Edit agent; its name stays fixed (#3219). - A trigger whose agent asks before a tool call says a run will wait for you, and Run unattended fixes it in one click (#3131).
- A finished run's Screen tab plays its own recording (#3204), and an open live viewer hears a Take over and a Hand back made from the run page's header (#3200).
- The Computer step keeps image, persistent, GPU, surface, exec and record across a switch where the new pick takes them, and names each one it drops (#3213). A workflow run's Graph names a map item by its label's head when the label is text (#3223). The Dev tools tab no longer scrolls sideways beside an open panel, and its cache finding compares a request only with its own conversation's (#3206).
Install, deploy and the command
- The first visit opens setup with its code filled in:
--open, the installer andagentrun service install|start|restartopen the setup page while the server has no owner,agentrun opendoes it at any time, and Settings → Webhook copies its secret in one press (#3119). agentrun doctorchecks how this AgentRun is set up and prints each problem with what to change: Node.js, the server and its version, the service, remote access, the console's password, models, harnesses, start-time switches and Docker. It is read-only and prints no token, key or code;--jsonfor agents (#3135).--public-url https://<name>/onnpx @parcha/agentrunandagentrun service installserves AgentRun at an address of your own behind a proxy you run; started on loopback with a signed-in Tailscale, the launcher says once how to serve it on the tailnet (#3140).agentrun stopnames a server running in the foreground and says to press Ctrl-C in its terminal (#3272).- A Helm chart, published with each release:
helm install agentrun oci://ghcr.io/parcha-ai/charts/agentrun --develruns the release's image as one pod on a 10 GiB volume, its token and seal key made as a Secret kept on upgrade and uninstall, with an optional Ingress whose address the server gets as its public address. The chart's version is the release's (#3252, #3253, #3262, #3267). - Coolify and Dokploy templates run the release's image as one service with its data on a volume (
deploy/coolify/agentrun.yaml,deploy/dokploy/agentrun/) (#3268). install.sh --vpspulls its image on every run, so a moving tag runs the registry's image (#3197), andAGENTRUN_TELEMETRY=0on a run again replaces the line its.envhas (#3230, #3244).importshows progress, stops cleanly on Ctrl+C after the session being saved and says what it took, and says Stopped only when sessions were left (#3151, #3278).
Docs and examples
- The README and
docs/getting-started.mdlead their local setup with the prompt to paste into a coding agent, the same text the website's copy button gives; the three manual steps follow it (#3286). - An example of Browser Use through Monid in a run (#3147).
- The server README records Particle-1's estimate matching Particle's own bill (#3233), a Render deploy walked from creation to first run in 85 s (#3226), and how to count runs with an unrecorded link before unsetting
DAYTONA_ARCHIL_EGRESS(#3241);docs/AUTOQA.md's expected results match the product (#3235).
CI and tests
- Every way in is walked on main each day (
npx @parcha/agentrunas published, the launcher, Docker Compose, Railway, Helm, Coolify, Dokploy, and Railway's and Render's own deploys when their secrets exist), and a red run opens an issue (#3271, #3276). The walks share one first run, the setup prompt is walked to a finished first run against 5 minutes, the Coolify and Dokploy walk keeps the first run's page as a screenshot, and the Render walk rides out the edge's 502 during a deploy (#3274, #3221, #3248, #3275, #3284). The Render walk runs the Railway walk's steps, and a walk Actions cancels finishes deleting what it made before it exits (#3287). - Internal simplifications with no change in behaviour, and test fixes (#3212, #3243, #3256, #3260, #3266, #3270, #3277).
Install
- Server:
npx @parcha/agentrun-serve@0.1.0-beta.47; every@parcha/agentrun-*package of this release is 0.1.0-beta.47 on npm - Launcher and CLI:
npx @parcha/agentrun@0.4.15 - Python client:
pip install parcha-agentrun==0.3.15 - Server image:
docker pull ghcr.io/parcha-ai/agentrun-server:v0.1.0-beta.47(linux/amd64, linux/arm64) - Helm chart:
helm install agentrun oci://ghcr.io/parcha-ai/charts/agentrun --version 0.1.0-beta.47