9agent

9agent

One launcher for Claude Code, Pi, and Hermes — pick a model from your gateway, launch the agent, optionally in Docker.

npm i -g 9agent
9agent                      # prompts: agent → model → mode

9agent -a claude -m ag/gemini-3.7-flash-high --yolo            # skip the prompts
9agent -a claude -m ag/gemini-3.7-flash-high --yes safe --sandbox   # ...and in Docker

Requirements

No gateway? You get Is 9Router running? and exit 1 — never a hang.

Flags

The gateway URL comes from --gateway, else NINEROUTER_URL. The key comes from the profile saved for that gateway, else NINEROUTER_KEY, else LOCAL_9ROUTER_KEY, else the sk_9router placeholder (a local placeholder, not a credential).

Save a key once, at a masked prompt, rather than typing it inline where it lands in shell history:

9agent --gateway https://router.example.com/v1 --key

Profiles live in ~/.config/9agent/config.json (mode 0600), one key per gateway URL. LOCAL_9ROUTER_KEY exists because a sandboxed agent reaches the gateway as a remote client, where the placeholder is rejected and a real key is required.

Sandbox runs invoke docker from PATH; set NINEAGENT_DOCKER_BIN to route them through something else, e.g. NINEAGENT_DOCKER_BIN="sudo -n docker" (requires passwordless sudo). Prefer adding yourself to the docker group — group membership and sudo grant the same power with less ceremony.

Anything after -- goes to the agent verbatim:

9agent -a claude -m ag/gemini-3.7-flash-high --yes safe -- --verbose

Agents

Pi and Hermes have no env var for the base URL, so the gateway must already be in their config. 9agent reads those files; it never writes them.

For Hermes, --safe-mode is not the opposite of --yolo — it disables customizations. Safe mode is simply omitting --yolo.

Sandbox

9agent -a claude -m ag/gemini-3.7-flash-high --yes safe --sandbox

Runs the agent in Docker — a blast-radius limiter, not a security boundary against a hostile agent. Only cwd and the agent home are mounted, and anything your host executes (hooks, plugins, settings) is mounted read-only. The container keeps full network egress — reaching the gateway requires it — so it bounds filesystem blast radius, not exfiltration.

docs/sandbox.md has the full threat model, the per-agent details, and the known limits.

Design

9agent resolves a model, execs the agent, and mirrors its exit code. It is not a session manager and not a config broker. Two rules follow:

• Never rewrites a config file you own — config-driven agents get a ShadowConfig copy instead.
• Never supervises what it starts — no wrapping, no proxying, no restarts, so exit codes and signals are the agent's own.

CONTEXT.md is the vocabulary. ADR-0001 records what this trades away.

Development

npm install
npm run dev          # tsx
npm run check        # typecheck, build, unit tests
npm run test:docker  # integration harness (needs Docker)
npm run release      # gate, build, verify the tarball, tag — CI publishes to npm

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md. Release history is in the changelog.

License

MIT — see LICENSE.