Runners API Reference

All runner endpoints are on the Gateway API (port 8002) under /gateway/admin/runners/.

Authentication: Include X-CM-API-Key header with a valid gateway API key.

Endpoints

POST /gateway/admin/runners/

Create a new managed runner.

Request Body:

{
  "provider_type": "e2b",         // "e2b" | "fake" | "claude_computer_use"
  "tool_profile": "locked",       // "locked" | "web_automation" | "full_vm_tools"
  "ttl_seconds": 3600,            // 60 - 86400
  "openclaw_version": "2026.2.14",
  "image_ref": null               // optional custom image
}

Response: RunnerResponse

GET /gateway/admin/runners/

List runners for the authenticated organization.

Query Parameters:

Response:

{
  "runners": [RunnerResponse],
  "total": 42,
  "limit": 100,
  "offset": 0
}

GET /gateway/admin/runners/{runner_id}

Get runner details including active session info.

Response: RunnerResponse

POST /gateway/admin/runners/{runner_id}/start

Start a new session on a ready runner.

Request Body (optional):

{ "ttl_override": 7200 }

Response: SessionResponse

POST /gateway/admin/runners/{runner_id}/stop

Stop the active session.

Query Parameters:

Response: SessionResponse

POST /gateway/admin/runners/{runner_id}/exec

Execute a command in the active session.

Query Parameters:

Request Body:

{
  "argv": ["echo", "hello"],
  "timeout_seconds": 30
}

Response: CommandResponse

POST /gateway/admin/runners/{runner_id}/terminate

Terminate a runner and all its sessions.

Response: RunnerResponse

GET /gateway/admin/runners/{runner_id}/events

Get audit events for a runner.

Query Parameters:

Response:

{
  "runner_id": "runner_abc123",
  "events": [EventResponse],
  "total": 15
}

GET /gateway/admin/runners/{runner_id}/stream

Stream real-time session output via SSE.

Query Parameters:

Content-Type: text/event-stream

Event Types:

• output — Command output text
• state_change — Runner/session state transition
• heartbeat — Keep-alive (every 15s)
• error — Error occurred
• done — Stream complete

GET /gateway/admin/runners/health

Check runner subsystem health.

Response:

{
  "status": "healthy",
  "provider": "e2b",
  "subsystems": {
    "feature_flag": true,
    "provider_available": true
  }
}

GET /gateway/admin/runners/prerequisites

Check runner setup prerequisites.

POST /gateway/admin/runners/canary

Run a canary lifecycle test (create -> start -> exec -> stop).

Type Schemas

RunnerResponse

{
  runner_id: string        // "runner_abc123"
  org_id: string
  state: "provisioning" | "ready" | "running" | "stopped" | "failed" | "terminated"
  provider_type: string
  tool_profile: string
  ttl_seconds: number
  version: number
  created_at: string       // ISO 8601
  updated_at: string
  session?: SessionResponse | null
}

SessionResponse

{
  session_id: string       // "sess_xyz789"
  runner_id: string
  state: "starting" | "active" | "stopping" | "expired" | "failed" | "terminated"
  started_at: string
  expires_at: string | null
}

CommandResponse

{
  command_id: string       // "cmd_abc123"
  session_id: string
  exit_code: number | null
  stdout: string | null
  stderr: string | null
}

EventResponse

{
  event_id: string
  event_type: string       // e.g. "runner_created", "command_executed"
  runner_id: string
  session_id: string | null
  actor: string
  detail: object
  timestamp: string
}

Event Types

RBAC Actions

Error Codes