coderClaw

Gateway runbook

Use this page for day-1 startup and day-2 operations of the Gateway service.

Symptom-first diagnostics with exact command ladders and log signatures. Task-oriented setup guide + full configuration reference.

</CardGroup>

5-minute local startup

```bash coderclaw gateway --port 18789 # debug/trace mirrored to stdio coderclaw gateway --port 18789 --verbose # force-kill listener on selected port, then start coderclaw gateway --force ``` ```bash coderclaw gateway status coderclaw status coderclaw logs --follow ``` Healthy baseline: `Runtime: running` and `RPC probe: ok`. ```bash coderclaw channels status --probe ``` Gateway config reload watches the active config file path (resolved from profile/state defaults, or `CODERCLAW_CONFIG_PATH` when set). Default mode is `gateway.reload.mode="hybrid"`.

Runtime model

One always-on process for routing, control plane, and channel connections.
Single multiplexed port for:
- WebSocket control/RPC
- HTTP APIs (OpenAI-compatible, Responses, tools invoke)
- Control UI and hooks
Default bind mode: loopback.
Auth is required by default (gateway.auth.token / gateway.auth.password, or CODERCLAW_GATEWAY_TOKEN / CODERCLAW_GATEWAY_PASSWORD).

Port and bind precedence

Setting	Resolution order
Gateway port	`--port` → `CODERCLAW_GATEWAY_PORT` → `gateway.port` → `18789`
Bind mode	CLI/override → `gateway.bind` → `loopback`

Hot reload modes

`gateway.reload.mode`	Behavior
`off`	No config reload
`hot`	Apply only hot-safe changes
`restart`	Restart on reload-required changes
`hybrid` (default)	Hot-apply when safe, restart when required

Operator command set

coderclaw gateway status
coderclaw gateway status --deep
coderclaw gateway status --json
coderclaw gateway install
coderclaw gateway restart
coderclaw gateway stop
coderclaw logs --follow
coderclaw doctor

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.

ssh -N -L 18789:127.0.0.1:18789 user@host

Then connect clients to ws://127.0.0.1:18789 locally.

If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.

```bash coderclaw gateway install coderclaw gateway status coderclaw gateway restart coderclaw gateway stop ``` LaunchAgent labels are `ai.coderclaw.gateway` (default) or `ai.coderclaw.` (named profile). `coderclaw doctor` audits and repairs service config drift. </Tab> ```bash coderclaw gateway install systemctl --user enable --now coderclaw-gateway[-].service coderclaw gateway status ``` For persistence after logout, enable lingering: ```bash sudo loginctl enable-linger ``` </Tab> Use a system unit for multi-user/always-on hosts. ```bash sudo systemctl daemon-reload sudo systemctl enable --now coderclaw-gateway[-].service ``` </Tab> </Tabs> ## Multiple gateways on one host Most setups should run **one** Gateway. Use multiple only for strict isolation/redundancy (for example a rescue profile). Checklist per instance: - Unique `gateway.port` - Unique `CODERCLAW_CONFIG_PATH` - Unique `CODERCLAW_STATE_DIR` - Unique `agents.defaults.workspace` Example: ```bash CODERCLAW_CONFIG_PATH=~/.coderclaw/a.json CODERCLAW_STATE_DIR=~/.coderclaw-a coderclaw gateway --port 19001 CODERCLAW_CONFIG_PATH=~/.coderclaw/b.json CODERCLAW_STATE_DIR=~/.coderclaw-b coderclaw gateway --port 19002 ``` See: [Multiple gateways](/gateway/multiple-gateways). ### Dev profile quick path ```bash coderclaw --dev setup coderclaw --dev gateway --allow-unconfigured coderclaw --dev status ``` Defaults include isolated state/config and base gateway port `19001`. ## Protocol quick reference (operator view) - First client frame must be `connect`. - Gateway returns `hello-ok` snapshot (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy). - Requests: `req(method, params)` → `res(ok/payload|error)`. - Common events: `connect.challenge`, `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `shutdown`. Agent runs are two-stage: 1. Immediate accepted ack (`status:"accepted"`) 2. Final completion response (`status:"ok"|"error"`), with streamed `agent` events in between. See full protocol docs: [Gateway Protocol](/gateway/protocol). ## Operational checks ### Liveness - Open WS and send `connect`. - Expect `hello-ok` response with snapshot. ### Readiness ```bash coderclaw gateway status coderclaw channels status --probe coderclaw health ``` ### Gap recovery Events are not replayed. On sequence gaps, refresh state (`health`, `system-presence`) before continuing. ## Common failure signatures | Signature | Likely issue | | -------------------------------------------------------------- | ---------------------------------------- | | `refusing to bind gateway ... without auth` | Non-loopback bind without token/password | | `another gateway instance is already listening` / `EADDRINUSE` | Port conflict | | `Gateway start blocked: set gateway.mode=local` | Config set to remote mode | | `unauthorized` during connect | Auth mismatch between client and gateway | For full diagnosis ladders, use [Gateway Troubleshooting](/gateway/troubleshooting). ## Safety guarantees - Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback). - Invalid/non-connect first frames are rejected and closed. - Graceful shutdown emits `shutdown` event before socket close. --- Related: - [Troubleshooting](/gateway/troubleshooting) - [Background Process](/gateway/background-process) - [Configuration](/gateway/configuration) - [Health](/gateway/health) - [Doctor](/gateway/doctor) - [Authentication](/gateway/authentication)

This site is open source. Improve this page.