// operate · runbooks

Operational runbooks

Short procedures for common incidents. Each runbook starts with diagnosis, narrows the likely cause and ends with recovery evidence.

Gateway is down or stuck

Check state
See whether the registered process still exists.
```
okami gateway --status
okami doctor --lint
```
Stop safely
If the PID is stale, stop also clears old state.
```
okami gateway --stop
```
Run in foreground
Use live logs to capture token, route or provider failures.
```
okami gateway --foreground
```

okami ps -w workspaces/defaultlist known processes

okami process log <id> -n 120read redacted logs

okami process signal <id> INTtry cooperative shutdown

okami process kill <id>kill process group or container when needed

okami process clean --ttl-hours 24 --dry-runinspect pruning without deleting

signal	action
missing auth	`okami auth list` and `okami login <provider>`
slow or weak model	`okami tune` to inspect failures by model
rate limit	temporarily switch `default_provider` or reduce parallelism
provider CLI broken	run the official CLI outside Okami, then `okami doctor`

Validate config
Confirm command, args and env.
```
okami config show
okami mcp
```
Test credentials
Tokens should come from .env, never hardcoded YAML.
```
env | grep GITHUB_TOKEN
okami doctor --lint
```
Reduce surface
Disable MCP servers one at a time until the failing bootstrap is isolated.
```
okami tools
```

okami memory search "problem term"find relevant facts

okami memory forget <id>remove a specific entry

okami persona-loglist persona/voice changes

okami persona-rollback 1undo the last evolution

okami replay --jsonconfirm whether the issue came from memory, tool or provider

okami config set OKAMI_API_TOKEN <strong-token>define required token

okami serve --host 127.0.0.1 --port 8765boot locally and fail-closed

curl -s http://127.0.0.1:8765/healthcheck unauthenticated health

curl -s http://127.0.0.1:8765/chat -H 'Authorization: Bearer <strong-token>' -H 'content-type: application/json' -d '{"message":"ping"}'

test auth and payload