revka doctor, status & self-test

Revka ships three diagnostic commands that answer three different questions. Use revka doctor to validate your configuration, workspace, and running daemon; revka status to print a one-screen summary of how the agent is configured (and as a Docker health probe); and revka self-test to verify that a fresh install actually works end to end. revka status (default report) and revka self-test --quick run fully offline; revka doctor is offline unless a local Kumiho CE backend is configured. revka self-test (no --quick) and revka doctor models perform network checks by default and require a running gateway. All three are safe to invoke at any time — note that revka self-test performs a transient memory write/delete round-trip, and revka doctor writes a temporary workspace probe file.

This page is your reference for diagnosing a Revka instance from the command line. For the metrics and tracing backends that feed these checks, see Observability & tracing.

Start here when something is wrong

revka doctor is the first step in any troubleshooting runbook. It validates config semantics, probes the workspace, and checks daemon freshness in one pass — most problems surface here before you need to read logs.

revka doctor

revka doctor runs a structured, multi-category diagnostic and prints a human-readable report with per-check severity indicators (ok, warn, error) grouped by category, followed by a summary line such as 12 ok, 2 warnings, 0 errors.

revka doctor

Internally each check produces a DiagResult { severity, category, message }, so the same diagnosis powers the dashboard’s doctor page as well as the CLI. See Logs, audit, doctor, pairing & skins for the dashboard view.

Diagnostic categories

revka doctor runs the following categories. A warn is informational and does not fail the run; an error indicates a problem you should fix before deploying.

Category	What it checks
config	Config file exists; provider valid; API key present; default model set; temperature in range (0.0–2.0); gateway port valid; fallback providers valid; model routes valid; embedding routes valid; at least one channel configured; delegate-agent providers valid
workspace	Directory exists and is writable; disk space (warns if under 100 MB); SOUL.md present (warn if missing); AGENTS.md present (warn if missing)
daemon	State file exists; heartbeat freshness; scheduler health; per-channel freshness
environment	git on PATH; $SHELL set; $HOME/$USERPROFILE set; curl on PATH
sidecars	If Kumiho is enabled — the venv Python exists, the kumiho package is importable, and the kumiho_memory package is importable
kumiho	For local Community Edition — probes GET /api/_live and GET /api/_health (Neo4j, Redis event-stream, embedding readiness)
cli-tools	Discovers configured CLI tools on PATH

Daemon freshness thresholds

The daemon category compares timestamps in the daemon state file against fixed thresholds. A component is reported stale when its last heartbeat exceeds the limit:

• Heartbeat — stale after 30 s
• Scheduler — stale after 120 s
• Channel — stale after 300 s

The check reads ~/.revka/daemon_state.json (written by the daemon every few seconds). If the file is absent, the daemon is assumed not running.

The kumiho_memory upgrade gap

The sidecars category specifically warns when kumiho is installed but kumiho_memory is not — common on installs that predate the kumiho_memory sidecar. The advanced memory reflexes stay disabled until you install it. Fix it with the venv’s own pip:

~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'

Then re-run revka doctor to confirm the warning clears. See Kumiho setup for backend details.

The config category does real validation, not just key presence — provider_validation_error actually attempts to construct the provider, and model/embedding routes plus delegate-agent providers are resolved. This makes revka doctor a useful pre-deploy gate.

revka doctor models

The models subcommand probes the live model catalog of every configured provider (or a single named provider) and prints a connectivity matrix: per-provider status, model count, and a detail message.

revka doctor models                          # probe all configured providers
revka doctor models --provider anthropic     # probe one provider
revka doctor models --provider openrouter --use-cache

Flag	Meaning
--provider <ID>	Probe only the named provider. Default: all known providers.
--use-cache	Prefer cached catalogs and skip the forced live refresh.

Per-provider results are classified, so a non-error outcome is not always a failure:

• ok — catalog fetched, model count reported.
• skipped — the provider does not support live model discovery (not an error).
• auth/access — HTTP 401/403/429, unauthorized, rate limit, or insufficient quota. Usually a missing or invalid API key.
• error — any other failure (connectivity, malformed response).

Note

When you pass --provider, the command fails (non-zero) only if that single provider could not be probed. Without --provider, the connectivity matrix reports each provider independently and the command succeeds. Use this to verify API keys before a deploy. For managing the catalog itself, see revka models, providers & auth.

revka doctor traces

The traces subcommand queries the runtime trace JSONL file written by the observability layer. It lists recent events newest-first (timestamp, id, event type, success, and a message preview), or fetches one event by UUID for full payload inspection.

revka doctor traces                             # 20 most recent events
revka doctor traces --limit 50                  # show 50 events
revka doctor traces --event tool_call           # filter by event type
revka doctor traces --contains "shell"          # case-insensitive text search
revka doctor traces --event tool_call --contains "timeout"
revka doctor traces --id <trace-id>             # full payload for one event

Flag	Meaning
--limit <N>	Maximum events to show. Default: 20.
--event <TYPE>	Filter by exact event_type (case-insensitive).
--contains <TEXT>	Substring match across event_type, message, payload, channel, provider, and model.
--id <UUID>	Fetch a single event and print its full payload as pretty JSON. Ignores other filters.

Each RuntimeTraceEvent carries id (UUID), timestamp (RFC 3339), event_type, optional channel / provider / model / turn_id / success / message, and a JSON payload. The list view truncates the message preview; --id shows the full payload.

Tracing is off by default

revka doctor traces reads observability.runtime_trace_path. If runtime_trace_mode = "none" (the default), the trace file does not exist and the command tells you how to enable it. Turn on rolling traces first:

[observability]
runtime_trace_mode = "rolling"                  # "none" | "rolling" | "full"
runtime_trace_path = "state/runtime-trace.jsonl"  # workspace-relative unless absolute
runtime_trace_max_entries = 200                 # rolling mode only

rolling mode trims on every append so the file never exceeds runtime_trace_max_entries lines. full mode grows unbounded — use it only for short-lived debugging. Trace payloads can contain model output, so keep tracing disabled on shared hosts. Details: Observability & tracing.

revka status

revka status prints a full one-screen summary of how this instance is configured. It reads config and local state only — no daemon required for the human-readable output.

revka status

The report includes:

• Version, workspace path, and config path
• Provider and model, plus the configured observability backend and trace storage mode/path
• Autonomy level and runtime kind (native / docker)
• Service state (running / stopped), heartbeat interval, and effective memory backend with auto-save state
• Security — workspace-only flag, allowed roots, allowed commands, max actions/hour, cost tracking (today / month spend versus limits when enabled), OTP status, and e-stop status
• Channels — every configured channel and whether it is set up

status —format exit-code

For scripts, monitors, and Docker HEALTHCHECK, pass --format exit-code. This skips the human-readable report and instead does a lightweight GET /health against the configured gateway, exiting 0 if the gateway is healthy and 1 otherwise.

revka status --format exit-code

Note

--format is a standard value flag, so --format exit-code and --format=exit-code are equivalent. The probe normalizes a bind host of [::] or 0.0.0.0 to 127.0.0.1, uses the configured gateway.port, and applies a 5-second timeout. It hits the same GET /health endpoint described in Status, health, config & tools endpoints.

Wire it into Docker Compose as the container liveness check:

healthcheck:
  test: ["CMD", "revka", "status", "--format=exit-code"]
  interval: 60s
  timeout: 10s
  retries: 3
  start_period: 10s

This is the canonical liveness check for containerized deployments. See Docker, Compose & one-click PaaS for the full container setup.

revka self-test

revka self-test verifies that an installation actually works — it opens the SQLite memory database, loads the provider and tool registries, parses the security policy, and (in full mode) exercises the gateway and a memory round-trip. It exits with code 1 if any check fails, which makes it suitable as a post-install or CI gate.

Full suite

revka self-test

Runs every check, including the network checks that require a running gateway.

Quick (offline)

revka self-test --quick

Skips the network checks (gateway health, memory round-trip, and WebSocket handshake). Suitable for offline or CI validation where no daemon is running.

Flag	Meaning
--quick	Skip all network checks — no gateway health check, no memory round-trip, no WebSocket handshake.

What gets checked

The quick suite (always run) covers:

1. config — the config file exists, loads, and parses.
2. workspace — the workspace directory exists and is writable (probed with a temp file).
3. sqlite — memory.db opens and responds to a query.
4. providers — the provider registry has entries.
5. tools — the core tool registry has entries.
6. channels — the channel configuration loads (reports channel types and how many are configured).
7. security — the security policy parses (reports the autonomy level).
8. version — version sanity check.

The full suite adds three network checks (skipped by --quick):

1. gateway — GET /health against the configured gateway returns success.
2. memory — a write / read / delete round-trip through the active memory backend.
3. websocket — a WebSocket handshake against ws://<host>:<port>/ws/chat.

Output is a numbered table with a per-check pass/fail mark and a summary line (All N checks passed. or N/M checks failed.). A non-zero exit means at least one check failed.

Which command do I want?

• revka self-test --quick right after install, before the daemon is up — confirms the binary, config, registries, and local storage are sound.
• revka self-test once the daemon is running — adds the gateway and memory round-trip checks.
• revka doctor for ongoing operational health — config validity, daemon/scheduler/channel freshness, sidecar and Kumiho backend status.
• revka status --format exit-code for an unattended liveness probe (Docker, load balancers, monitors).

Related pages

Observability & tracing Enable runtime traces, choose a metrics backend, and read the /metrics and /health endpoints.

Updating, runbook & troubleshooting Where doctor, status, and self-test fit in the incident-triage flow.

Status, health, config & tools endpoints The GET /health and GET /api/health endpoints behind status --format exit-code.

revka models, providers & auth Refresh and manage the provider catalogs that doctor models probes.