Skip to content

DRIVER.md

Latest commit

 

History

History
215 lines (155 loc) · 6.14 KB

DRIVER.md

File metadata and controls

215 lines (155 loc) · 6.14 KB

Claw Driver Protocol

Claw drivers are standalone binaries named claw-driver-<arch> that communicate with the claw CLI via newline-delimited JSON (NDJSON) on stdin/stdout.

Discovery

Drivers are discovered by searching:

  1. ~/.claw/drivers/
  2. $PATH

Any executable matching claw-driver-* is treated as a candidate driver.

Message Format

All messages are single-line JSON objects with a "type" field.

Request/Response Types

version_request / version_response

Used to identify the driver and check compatibility.

{"type": "version_request", "source_dir": "/path/to/install"}
{
  "type": "version_response",
  "arch": "nanoclaw",
  "arch_version": "1.2.3",
  "driver_version": "0.1.0",
  "claw_protocol": "0.1.0",
  "driver_type": "local",
  "requires_config": []
}

probe_request / probe_response

Used for auto-detecting architecture from a directory.

{"type": "probe_request", "source_dir": "/path/to/install"}
{"type": "probe_response", "arch": "nanoclaw", "confidence": 0.9}

ps_request

List running agent instances.

{"type": "ps_request", "source_dir": "/path/to/install"}

Driver emits zero or more instance messages, then a completion:

{"type": "instance", "id": "nanoclaw-main", "arch": "nanoclaw", "group": "main", "folder": "main", "jid": "...", "state": "running", "age": "3m", "is_main": true}
{"type": "ps_complete", "warnings": []}

agent_request

Send a prompt to an agent.

{
  "type": "agent_request",
  "source_dir": "/path/to/install",
  "group": "main",
  "jid": "",
  "prompt": "What is 2+2?",
  "session_id": "",
  "resume_at": "",
  "native": false,
  "verbose": false,
  "timeout": "5m",
  "ephemeral": false
}
  • native — run without a container (driver-specific; nanoclaw runs the agent-runner via Node.js). Drivers that don't support native mode may ignore this field.
  • verbose — pipe agent-runner/container diagnostic stderr to the terminal.
  • timeout — max duration for the agent response (Go duration string, e.g. "30s", "5m"). Driver kills the agent process on deadline and returns agent_complete with status: "timeout".
  • ephemeral — use a disposable workspace with no session persistence. Workspace is removed after the run. Mutually exclusive with session_id.

Driver streams output chunks, then a completion:

{"type": "agent_output", "text": "...", "chunk": true}
{"type": "agent_complete", "session_id": "abc123", "status": "success", "input_tokens": 42, "output_tokens": 11}

Status values: success, error, timeout. Omit session_id when ephemeral is true.

watch_request

Stream messages from the database in real time.

{
  "type": "watch_request",
  "source_dir": "/path/to/install",
  "group": "main",
  "jid": "",
  "lines": 20
}

Driver emits historical messages then polls for new ones:

{"type": "message", "timestamp": "2026-03-26T10:01:33Z", "sender": "You", "content": "Hello", "is_bot": false}

The driver exits when the orchestrator closes stdin.

health_request

Run health diagnostics against an installation.

{
  "type": "health_request",
  "source_dir": "/path/to/install",
  "group": "",
  "checks": ["runtime", "credentials", "database", "disk", "sessions", "groups", "skills", "image"]
}
  • group — if non-empty, scope group-level checks to this group only
  • checks — list of checks to run; omit or send [] for all

Driver emits one check_result per check, then a completion:

{"type": "check_result", "name": "runtime", "status": "pass", "detail": "docker 27.3.1"}
{"type": "check_result", "name": "disk", "status": "fail", "detail": "group dir 94% full", "remediation": "Free up space or move groups to a larger volume"}
{"type": "health_complete", "pass": 5, "warn": 1, "fail": 1}

Status values: pass, warn, fail. Optional remediation field provides a suggested fix.

Drivers that don't implement health checks return {"type": "error", "code": "UNSUPPORTED"}.

groups_request

List registered groups for an installation.

{"type": "groups_request", "source_dir": "/path/to/install"}

Driver emits zero or more group messages, then a completion:

{"type": "group", "source_dir": "/path/to/install", "jid": "...", "name": "main", "folder": "main", "trigger": "@Andy", "is_main": true, "requires_trigger": false}
{"type": "groups_complete"}

Drivers that don't support groups return {"type": "error", "code": "UNSUPPORTED"}.

sessions_request

List recent sessions for a group.

{"type": "sessions_request", "source_dir": "/path/to/install", "group": "main", "limit": 50}
  • group — group name (fuzzy match) or JID
  • limit — max sessions to return (default: 50)

Driver emits zero or more session messages, then a completion:

{"type": "session", "session_id": "abc123", "group": "main", "started_at": "2026-03-27T09:00:00Z", "last_active": "2026-03-27T09:45:00Z", "message_count": 12, "summary": "Reviewed deploy config"}
{"type": "sessions_complete"}

error

Any request can result in an error:

{"type": "error", "code": "GROUP_NOT_FOUND", "message": "no group matching 'foo'"}

Error Codes

Code Meaning
PARSE_ERROR Invalid JSON received
UNKNOWN_TYPE Unrecognized message type
MISSING_PROMPT agent_request without a prompt
GROUP_NOT_FOUND Could not resolve the specified group
NO_RUNTIME No container runtime (docker/container) found
SPAWN_ERROR Failed to start the agent container or process
DB_ERROR Database read error
NATIVE_NO_NODE --native requested but node not found in PATH
NATIVE_NO_DIST --native requested but agent-runner dist not built
UNSUPPORTED Driver does not implement the requested message type
CHECK_ERROR A health check could not be run (distinct from a failed check)

Lifecycle

  1. The orchestrator spawns the driver binary
  2. Sends one NDJSON request on stdin
  3. Reads NDJSON responses from stdout
  4. For watch_request: closes stdin to signal the driver to exit
  5. For all others: the driver exits after sending the completion message