Daemon lifecycle
serve, start, stop, restart, reload, status — run and control the local BitRouter daemon your agent talks to.
Your agent never talks to a remote API directly — it points at the binary running locally, by default on http://127.0.0.1:4356. Everything else in these docs — the four model protocols, the MCP and ACP gateways — is served from that one endpoint. These six commands run and control it.
bitrouter serve
Load a config, run migrations, and serve HTTP + control socket in the foreground
Usage: bitrouter serve [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml. When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults (bitrouter init is the explicit way to scaffold a file) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
Runs in the foreground — the form you want under a process supervisor or in a container:
bitrouter serve -c ./bitrouter.yamlbitrouter start
Spawn bitrouter serve as a detached background process
Usage: bitrouter start [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml (passed through to the child) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--log <LOG> | Path to redirect the daemon's stdout/stderr to. Defaults to bitrouter.log inside the config file's directory (e.g. ~/.bitrouter/bitrouter.log) so it lives alongside the socket and pid file rather than in the launcher's CWD |
Daemonizes: writes a pidfile and detaches. stop/restart target the pidfile; reload hot-loads config changes without dropping in-flight connections.
bitrouter stop
Send a stop command to a running daemon
Usage: bitrouter stop [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml (used to locate the control socket). Resolves via the standard chain: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--socket <SOCKET> | Explicit control socket path. Overrides the config-derived path |
bitrouter restart
stop then start — config path is passed through
Usage: bitrouter restart [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml. When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults (bitrouter init is the explicit way to scaffold a file) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--socket <SOCKET> | Explicit control socket path. Overrides the config-derived path |
--log <LOG> | Path to redirect the new daemon's stdout/stderr to. Defaults to bitrouter.log next to the config file |
bitrouter reload
Hot-reload the running daemon's config / routing table
Usage: bitrouter reload [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml (used to locate the control socket) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--socket <SOCKET> | Explicit control socket path. Overrides the config-derived path |
bitrouter status
Report a running daemon's status (pid, listen address, model count). Prints running: no when no daemon is reachable
Usage: bitrouter status [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml (used to locate the control socket) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--socket <SOCKET> | Explicit control socket path. Overrides the config-derived path |
Prints running: no when no daemon is reachable — safe to poll in scripts.
How is this guide?
CLI reference
The bitrouter binary — one local endpoint your runtime points at, a daemon you control, and a scriptable surface for routing, policy, and your Cloud account.
init & config
The onboarding wizard and config tooling — write the starter bitrouter.yaml, validate it against the published schema.