# agent-run `agent-run` is a self-contained Rust supervisor for Codex, Claude Code, and GLM coding agents. It runs children as durable asynchronous jobs, records verified outcomes in SQLite, tracks provider capacity, and exposes the same tool surface through its CLI, MCP stdio server, and Unix-socket JSON-RPC API. The native Agent Run binaries and per-user installer do not require Python. The optional shared systemd wrapper uses Python 3 for readiness checks. Engine CLIs remain external dependencies and must be installed and authenticated separately. ## Release targets The release workflow builds and verifies native archives for macOS Apple silicon (`aarch64-apple-darwin`) and Linux x86-64 (`x86_64-unknown-linux-gnu`). Both native checks must pass before publication. Existing releases may contain only the macOS archive; Linux availability begins with a release built by the updated workflow. The Linux binary is built on Ubuntu 22.04 and requires a compatible glibc environment. Keychain and launchd integration remain macOS-only. ## Family standard agent-run declares its adoption of the Agent MCP family standard in [`family.toml`](family.toml): a resident+local profile, one dispatcher behind the CLI, stdio MCP, and the Unix-socket API, a pinned compiler/SDK baseline, and the sealed-archive delivery contract. The declaration and the managed adoption files in `.family/` are verified by `cargo xtask family verify` inside `cargo xtask check`. What is adopted, what is only observed, and what remains open is recorded truthfully in [docs/family-standard.md](docs/family-standard.md); it is a declaration, not a compliance certificate. ## Install Use the same command for a fresh installation or an update: ```bash curl -fsSL https://github.com/DKotsyuba/agent-run/releases/latest/download/install.sh | sh ``` Or use wget: ```bash wget -qO- https://github.com/DKotsyuba/agent-run/releases/latest/download/install.sh | sh -s -- --downloader wget ``` **Availability:** the installer is included starting with 0.14.0. Releases through 0.13.3 do not contain its script/helper. An older macOS-only release cannot install on Linux; the bootstrap reports when the selected release does not contain the Linux archive. The current bootstrap requires trusted `gh`, `jq`, `tar` and a SHA-256 utility. `curl` and `wget` can download the entrypoint or payload, but GitHub CLI still verifies the expected repository, workflow, annotated tag and full source commit against the payload's attestation before the installation helper executes. Private downloads require an existing GitHub CLI authentication; the installer does not install tools or sign in automatically. The one-line command executes GitHub's current bootstrap over HTTPS. For a reviewable entrypoint, download `install.sh` from an exact release tag and inspect it before running it. This bootstrap requires the external family release manifest; older releases retain their own version-bound installers and sealed directory rollback support. It never silently falls back to checksum-only trust. The installer verifies the download and release manifest, retains immutable versions under `~/.agent-run/standalone/releases`, and places a launcher in `~/.local/bin`. Add that directory to `PATH`. No Cargo, Python or sudo is needed. Repeat the command to select the latest compatible version. Existing config, accounts and database are preserved; updates include a state/config backup. Stop the broker and other agent-run services before updating. Active agents, incompatible configuration or a schema migration requirement block the update. For an existing 0.13.x schema-2 home, first use the new candidate's [paired configuration/database migration](docs/provider-migration.md#existing-schema-2-homes). Services are not stopped or restarted automatically. Afterward, restart your configured services and run `agent-run doctor`. To pin a version or choose directories, download `install.sh` and run: ```bash sh install.sh --version X.Y.Z --home "$HOME/.agent-run" \ --prefix "$HOME/.agent-run/standalone" --bin-dir "$HOME/.local/bin" ``` For a fresh install, run `agent-run init`, then configure engine CLIs and accounts. The installer does not install engines or sign in to providers. Build from source with the pinned Rust toolchain (also usable before publication): ```bash release_root="$(mktemp -d)" version="$(awk -F '"' '/^version = / { print $2; exit }' Cargo.toml)" cargo xtask release build-native --output "$release_root" --version "$version" "$release_root/releases/$version/bin/agent-run-deploy" install \ --release "$release_root/releases/$version" --version "$version" \ --prefix "$HOME/.agent-run/standalone" --home "$HOME/.agent-run" --bin-dir "$HOME/.local/bin" ``` Use a new version for changed source: the installer never overwrites an existing version with different bytes. The temporary build directory may be removed after installation; the selected release is copied into the prefix. The home defaults to `~/.agent-run`; override it with `AGENT_RUN_HOME` or `--home`. ## Configure Configuration lives in `/config.toml`. Schema 2 declares native harnesses, named providers, explicit models and account bindings. See [provider configuration](docs/provider-config-v2.md) for a complete example. Agent Quota collects and evaluates quotas independently. Configure Run to read its local socket: ```toml [capacity.quota] socket = "/absolute/path/to/agent-quota.sock" # expected_service_uid = 1000 # optional; defaults to Run's effective UID ``` If Quota is unavailable, Run treats quota as unknown and can still start an agent; the provider may then refuse it. Run does not send native quota failures back to Quota. Previously installed collection jobs must be migrated separately to Agent Quota; they do not supply the new Quota service. Credentials stay in protected account stores. The broker checks configuration every minute and on requests; invalid revisions keep the last valid settings. Declare shared background backends under `services.`. The broker warms them before harness launch, retains them while agents are active, and stops them after thirty minutes of inactivity. Native MCP clients connect to their usual backend; their tool permissions remain defined by the role. See [managed services](docs/managed-services.md), including the CodeGraph example. Initialize and inspect the installation: ```bash agent-run init agent-run doctor ``` ## Run the broker `start` is broker-owned: it submits through the resident Unix socket and never falls back to a worker owned by the short-lived CLI process. ```bash agent-run api serve ``` For a long-lived macOS installation: ```bash plist="$HOME/Library/LaunchAgents/com.agent-run.api.plist" agent-run api launchd --binary "$(command -v agent-run)" \ | plutil -extract plist raw -o "$plist" - launchctl bootstrap "gui/$(id -u)" "$plist" ``` Linux can run the same broker under systemd. An optional shared-service example in [`scripts/systemd`](scripts/systemd/) runs one broker and account-owned launch workers under one unit; the host configures its users, groups and socket permissions. See the [shared-service plan](docs/linux-system-service-plan.md). The [Linux access guide](docs/linux-access-control.md) explains account, group, socket, credential and shared-service setup for other installations. ## Use the CLI ```bash agent-run delegation-guide # read before choosing a delegation route agent-run delegation-guide --provider codex --profile review # exact optional filters agent-run start --provider codex --model gpt-6.1-sol --profile review \ --task "Review this repository." --workdir "$PWD" agent-run agents agent-run answer ag-... agent-run transcript ag-... agent-run transcript ag-... --follow --format text agent-run resume ag-... --task "Continue with the highest-priority finding." ``` Output is line-delimited JSON except for the plain-text `delegation-guide` and text transcript rendering. Before every delegation, call `delegation_guide` (CLI: `agent-run delegation-guide`) and read it before choosing provider, model, effort or profile. `transcript --follow` streams a live view: model text, tool activity, and results as they arrive, exiting when the agent reaches a terminal state and its journal is drained; Ctrl-C exits only the viewer and never cancels the agent. `--format text|json` picks the rendering, defaulting to text on a terminal and JSON when output is piped. In text mode each journal fragment is sanitized and written to the pipe immediately as it arrives — there is no line buffering — with one newline per message or tool row; untrusted roles, names, and content are stripped of terminal escape sequences. The Codex runtime journals deltas and completion tails of one message under a shared item identity, so they render as one continuous row; the Claude runtime journals assistant fragments and the completion tail of one message under its native message id (or one producer-owned fallback per message boundary when the engine omits ids), so each message renders as one continuous row and distinct messages stay distinct. Other commands include `steer`, `cancel`, `delivery status`, and `doc`. Quota windows, reset times and capacity standing are presented by Agent Quota (for example `agent-quota limits`), not by Run; Run keeps only the Quota read its admission needs and refuses an exhausted choice with `QuotaExhausted`. ## Use the MCP server The MCP process is a thin stdio proxy over the resident broker: ```json {"command":"agent-run","args":["--home","/absolute/path/to/agent-run-home","mcp"]} ``` It advertises the orchestrator tools `start`, `start_batch`, `resume`, `cancel`, `steer`, `list_agents`, `answer`, `transcript`, `delegation_guide` and `doc`. Use `delegation_guide` with optional exact `provider`, `model`, and `profile` filters for routing; it carries no quota standing. Service integration methods used by Agent Pool and Hub — `status`, `batch_receipt`, `capabilities`, `transcript_exact`, `initial_task`, `answer_chunk`, `agent_integration`, `history_pins_list` and `history_pins_release` — are served only by the operator socket and CLI; the socket `tools` method lists them with `"surface":"socket"`. See [the API reference](docs/api.md#transport-surfaces). `start_batch` atomically admits 1–20 independent jobs and returns a permanent receipt of their stable IDs, execution sequences and opaque execution references. An identical request ID and intent replay that receipt without starting another job. Admission does not promise every supervisor starts; inspect each agent's status. The complete request still has to fit the existing transport and writer limits. Automatic multi-agent hook binding is not provided: pass an explicit `orchestrator` for each job that needs its own completion notice. Set `retain_history:true` to keep each admitted lineage's database history through an owner release. Direct socket clients receive the batch's `release_token` in the first admission response and pass it with the pin ID to `history_pins_release`. CLI callers can capture it with `start-batch --release-token-file PATH` or `--release-token-fd N`, then release with `agent-run history-pins release --pin-id PIN_ID --release-token-file PATH`. MCP and CLI standard output carry the receipt only. The offline database owner can recover legacy pins and pins with no saved token using `agent-run history-pins release-offline --expected-store-id STORE_ID --pin-id PIN_ID --request-id BATCH_REQUEST_ID`. Active pins also retain process-ownership evidence and recovery details for the lineage. See the [pin release contract](docs/api.md#agent-pool-migration-for-history-pins). New schema-2 workers receive a separate built-in MCP: `notify_orchestrator`, plus `health_reply` and `finish` in explicit-completion mode (research roles add `save_report`). Ordinary work MCPs remain profile-controlled. Agent Run 0.32.0 removed its legacy cooperative pools (`start_pool`, `pool`, `pool_post`, `pool_replace`, `list_pools`, the worker `pool_*` tools and the matching CLI commands). Agent Pool owns groups, membership, messages and consensus; old pool rows stay readable through read-only SQL (`agent-run doc completion`). See [worker reports](docs/worker-mcp.md) for bounds, replies and upgrade behavior. ## Use the socket API The broker binds `/api.sock` with mode `0600`. It accepts newline-framed JSON-RPC 2.0 and provides the tool methods plus `ping`, `tools`, and `wait`. See [docs/api.md](docs/api.md). ## Observe sessions The `agent-run-tui` terminal observer was removed in 0.32.0; use Agent Hub, or `agent-run agents` and `agent-run transcript`. Releases still seal `bin/agent-run-tui` as a fixed compatibility shim that reports the move and exits non-zero, so an existing launcher keeps a clear message. ## Reliability contract - SQLite admission precedes execution, so accepted jobs remain durable. - Success requires answer proof, completion evidence, and verified cleanup. - Generated runtime homes include only declared auth bridges, tools, skills, hooks, plugins, and policy. - The broker checks configuration hashes every 60 seconds and on requests. - Release directories are immutable, checksummed, and gated by `COMPLETE`. Development and release procedures are in [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/releasing.md](docs/releasing.md).