launch, spawn & tui
Run coding-agent harnesses pointed at the local daemon — interactive, headless sub-agents, or the orchestrator TUI.
Three ways to run a harness on top of the daemon: launch for an interactive session, spawn for a headless sub-agent, and tui for the orchestrator console.
bitrouter launch
Launch a coding-agent harness (Claude Code or Codex) as an interactive native-TUI child, with its API base URL pointed at the local BitRouter daemon — no agent config files are touched. The human drives the harness's own TUI directly; this is the main orchestrator surface (use bitrouter spawn for headless ACP sub-agents). Follows cargo run's separator convention: bitrouter options come before --, everything after -- is forwarded to the agent verbatim, e.g. bitrouter launch -a codex -- --model openai/gpt-5-codex.
The agent authenticates to BitRouter with BITROUTER_API_KEY when it is set; otherwise a local placeholder is used (fine under the skip_auth default written by bitrouter init). A missing agent binary is offered for install via its official native installer.
Usage: bitrouter launch [OPTIONS] --agent <AGENT> [-- <AGENT_ARGS>...]
Arguments
| Argument | Description |
|---|---|
[AGENT_ARGS]... | Arguments forwarded verbatim to the agent binary. Everything after -- lands here |
Options
| Flag | Description |
|---|---|
-a, --agent <AGENT> | Which agent harness to launch Possible values: |
- claude: Anthropic's Claude Code CLI (claude) | |
- codex: | OpenAI's Codex CLI (codex) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
-c, --config <CONFIG> | Path to bitrouter.yaml (used to derive the daemon base URL). When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults |
--human | Render the human-readable view to stdout instead of JSON |
--base-url <BASE_URL> | Override the agent's API base URL instead of deriving it from server.listen (e.g. when the daemon listens on a non-default address or a remote BitRouter) |
--no-install | Never offer to install a missing agent — fail with the install command instead. (Auto-implied when stdin is not a TTY.) |
--no-start | Never auto-start a local BitRouter daemon when none is running — just warn. (A --base-url or non-local target is never auto-started regardless.) |
--check | Check the agent binary, BitRouter base URL, and route compatibility without launching the agent |
bitrouter launch claudePoints the harness's API base URL at the local daemon — the same wiring the Integrations recipes do by hand — and prints a session spend summary on exit.
bitrouter spawn
Spawn an ACP-compatible harness as a headless sub-agent, routed through the BitRouter daemon by default. Pick a mode: -p "<text>" streams one prompt as NDJSON then exits; --serve speaks ACP over stdio for a GUI/manager; --check preflights the route. Pass --direct to bypass daemon routing. (For an interactive native TUI use bitrouter launch.)
Usage: bitrouter spawn [OPTIONS] [AGENT] [-- <AGENT_ARGS>...]
Arguments
| Argument | Description |
|---|---|
[AGENT] | ACP agent id: a bundled-catalog id (claude-acp, codex-acp, gemini-cli, pi-acp) or a configured agents: entry. A catalog id needs no config entry |
[AGENT_ARGS]... | Forwarded verbatim to the interactive agent in the deprecated --agent path (everything after --) |
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
-p, --prompt <TEXT> | Send one prompt, stream NDJSON to stdout, then exit |
--human | Render the human-readable view to stdout instead of JSON |
--serve | Serve the session as a vanilla ACP Agent over stdio (GUI/manager) |
--check | Preflight the harness + route without launching anything |
--direct | Do NOT route through the daemon — let the harness use its own provider auth. Routing is on by default |
--model <MODEL> | Pin the harness's model (via its model env var / -c model=) |
--base-url <BASE_URL> | Override the gateway base URL (else derived from server.listen) |
--no-start | Never auto-start a local daemon when none is running — fail fast |
--worktree <WORKTREE> | Provision (or reuse) a git worktree for the session |
--rm-worktree | Remove the worktree when the session ends (only one this session created). Off by default — removal discards uncommitted work |
--no-transcript | Disable the durable session transcript (on by default) |
--turn-timeout <SECS> | Per-turn deadline in seconds |
--no-wait | (with -p) Return immediately after submitting the prompt |
--warm | (with --serve) Keep the session alive for reattach after the manager disconnects. Unix-only |
--idle-timeout <SECS> | (with --serve --warm) Shut down after this many idle seconds [default: 1800] |
-c, --config <CONFIG> | Path to bitrouter.yaml. Resolves via the standard chain when omitted |
bitrouter spawn -p "summarize the diff" --model @codingSpawns an ACP-compatible harness as a headless sub-agent, routed through the daemon by default. This is the mechanism behind the Subagent feature.
How is this guide?