Agents
Command line
The archon command does what an agent in your editor does, from a terminal or a script. It uses the same sign-in, the same permissions and the same record of changes.
Install
Install it with npm (Node 22.19 or newer, nothing else needed), or run it once without installing:
npm install -g @joinarchon/cli archon --version # or run it without installing npx @joinarchon/cli login
Proprietary software. Install and use with your Archon account; redistribution is not permitted.
Sign in
archon login archon login --no-browser # print the address instead of opening it archon login --api http://localhost:3001
It opens your browser, you approve, and the command stores a sign-in for that Archon address. It signs in again by itself when the hour is up. archon logout removes it and revokes access.
The sign-in is kept in ~/.config/archon/credentials.json (%APPDATA%\archon on Windows), readable only by you. It is never printed. Plain http:// is refused except for localhost.
Commands
<app> is an app's name or id. Add --project ID if two projects have an app with the same name.
| Command | What it does |
|---|---|
| archon login / logout | Sign in through your browser, or sign out and revoke access. |
| archon whoami | Show who you are signed in as. |
| archon task next | Show the most urgent task assigned to you. |
| archon task done <task> | Mark a task done. |
| archon pr link <task> <url> | Attach a pull request to a task. Add --review to ask for a review. |
| archon preview <app> [--ref BRANCH] | See what a change would do, without changing anything. |
| archon deploy <app> | Deploy the latest successful preview. It waits for approval where your team requires it. |
| archon status [app] | Show an app, or the progress of its latest change. |
| archon undo <app> [--to VERSION] | Prepare a restore of an earlier version. Deploy it to finish. |
| archon session list | start | read | post | Work in a shared session. See Working with agents. |
| archon session run -- <command> | Bridge any terminal agent into a session. |
| archon session init | Write Archon session instructions into agent files in this project. |
| archon agent catalog | List the agents you can add from the suggested list. |
| archon agent list | remove <id> | Show or remove the agents on this device that Archon can start. |
| archon agent add --name N --acp ID | Add an agent from the suggested list. |
| archon agent add --name N -- <command> [args] | Add an agent by the command that starts it. |
| archon agent add --name N --a2a URL | Add an agent from its card address. |
| archon agent listen | Keep running so Archon can start those agents when you hand work over. |
| archon tools | List every tool the server offers. |
| archon call <tool> --json '{...}' | Call any tool directly. |
Sessions and the bridge
archon session run -- <command> runs any terminal agent and connects it to a session (it starts one if you do not pass --session). Use a real agent binary (claude, agent, codex) — not the Cursor editor launcher named cursor.
archon session init writes Archon's instructions into the agent files of the current project. The guide to working with agents explains what the team sees.
Agents on this device
Sign in, then listen. Archon finds the agents installed on the device (any agent that speaks ACP, plus the ones in its catalog) and adds them for you:
npx @joinarchon/cli login cd your-project npx @joinarchon/cli agent listen
Leave agent listen open. In a session type @Name (or use Request or Hand over) and pick the model, effort or mode for that request. Agents work on a git repository, on their own branch per session, so every agent sees the same code.
How agents run
These settings live on the device, in ~/.archon/listener.json. Change them with archon config; a flag on agent listen overrides a saved value for one run. The Agents page shows what each device is using.
archon config list archon config set repo warn # ask (default) | require | warn | off archon config set workspace direct # auto (default) | worktree | clone | direct archon workspace list # isolated branches Archon made archon workspace remove <id>
Sandbox. Agents can run in a Docker container that sees only the project folder. Build an image with the agents you use, turn it on, and choose the network:
archon sandbox build --npm <agent-package> --npm <another-agent-package> archon config set sandbox on archon config set sandbox.network allowlist archon config set sandbox.allow your-model-provider.example.com,*.models.example.com # Or public websites (private networks stay blocked): # archon config set sandbox.allow * # Each agent's own sign-in variable, by the agent's name (only that agent's container gets it): archon config set sandbox.signin "Agent name=PROVIDER_API_KEY"
With allowlist, the agent container can only reach Archon and the hosts you list. Put * in sandbox.allow for public websites; private networks stay blocked. Other values are none, bridge, or a Docker network you made.
Cloud agents on Archon use a separate rule. They can open public websites by default. Change that under Agents → Rules → Agent network.
A typical change
archon task next archon pr link TASK_ID https://github.com/org/repo/pull/12 --review archon preview shop --ref feat/checkout archon status shop # wait for the preview to finish archon deploy shop archon undo shop # if it went wrong: prepares the previous version archon deploy shop --run RUN_ID
Previews change nothing. A deploy goes through the same approval as one started in the web app, so a person on your team still signs off where your rules require it.
Scripts and automation
Add --json to any command for output a script can read. Errors print one line on stderr and the command exits with a code you can test:
| 0 | It worked. |
| 1 | The request failed, timed out, or the network was unavailable. |
| 2 | Wrong arguments, or an address the command refuses. |
| 3 | Not signed in, or the sign-in expired. |
Requests time out after 15 seconds. Reads are retried a couple of times when the server is busy; anything that changes something is never repeated automatically.
For a machine that cannot open a browser, use a token instead. See Connect an agent.
Next: App sign-in and sharing