Runtimes API

{
  runtimes: Array<{
    // back-compat shape (leading fields)
    id: 'claude-code' | 'codex' | 'hermes' | 'clawboo-native'
    participantKind: 'agent' | 'human'
    capabilities: {
      streaming: boolean
      mcp: boolean
      worktrees: boolean
      resume: boolean
      toolApproval: boolean
      models: string[]
      contextWindowTokens?: number
      runtimeClass?: 'wrapped-oneshot' | 'connected-substrate' | 'native'
      nativeHome?: { scope: 'per-identity' | 'per-run'; persist: boolean }
      nativeSkills?: 'preserve' | 'none'
      nativeMemory?: 'preserve' | 'none'
      nativeChannels?: 'gateway' | 'none'
      nativeScheduler?: boolean
    }
    health: { ok: boolean; message?: string }
    // install/auth status fields (spread from runtimeStatus)
    name: string
    installed: boolean
    binPath: string | null
    builtIn: boolean
    authKind: 'api-key' | 'oauth' | 'none'
    envVar: string | null
    hasCredential: boolean
    hasVaultCredential: boolean
    loggedIn: boolean // oauth runtimes only: an existing `codex login` was detected
    codexAuth: boolean // hermes only: a ChatGPT-subscription login is present
    installCommand: string | null
    docsUrl: string
    connectionState: 'not-installed' | 'needs-auth' | 'needs-login' | 'ready' | 'unknown'
  }>
  available: Array<{
    id: string
    name: string
    healthBin: string | null
    packageManager: 'npm' | 'pip' | null
    installCommand: string | null
    builtIn: boolean
    authKind: 'api-key' | 'oauth' | 'none'
    envVar: string | null
    docsUrl: string
    headlessAuth: boolean
  }>
}

{ "error": "<message>" }

curl http://localhost:18790/api/runtimes

{ "error": "Clawboo Native is built in — nothing to install" }

data: {"type":"progress","step":"installing","message":"Installing Claude Code…"}

data: {"type":"output","line":"added 1 package in 3s"}

data: {"type":"complete","success":true}

curl -N -X POST http://localhost:18790/api/runtimes/claude-code/install

{
  apiKey?: string     // required for api-key runtimes (non-ollama)
  provider?: string   // clawboo-native only: routes the key to the provider's env var
}

{
  ok: true,
  connectionState: 'ready' | 'needs-login' | 'not-installed',
  loginCommand: 'codex login',
}

{ ok: true, connectionState: 'not-installed' | 'needs-auth' | 'needs-login' | 'ready' | 'unknown' }

{ "error": "apiKey is required" }

{ ok: true, connectionState: 'ready' }

# Claude Code (api-key)
curl -X POST http://localhost:18790/api/runtimes/claude-code/connect \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"sk-ant-..."}'

# Native, choosing OpenRouter
curl -X POST http://localhost:18790/api/runtimes/clawboo-native/connect \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"sk-or-...","provider":"openrouter"}'

{ ok: true, connectionState: 'needs-auth' | 'needs-login' | 'ready' | 'not-installed' | 'unknown' }

curl -X POST http://localhost:18790/api/runtimes/hermes/disconnect

{ "error": "runtime '<id>' has no sign-out" }

{ "error": "<name> is not installed" }

{ ok: true, connectionState: 'needs-login' }  // signed out
{ ok: false, connectionState: 'ready' }       // still logged in

curl -X POST http://localhost:18790/api/runtimes/codex/logout

{
  provider?: string   // 'anthropic' | 'openai' | 'openrouter' | 'ollama' |
                      // 'google' | 'xai' | 'groq' | 'mistral' | 'together' |
                      // 'cerebras' | 'moonshot'
  apiKey?: string     // optional: omit to probe the key already stored for
                      // `provider`. Required only when nothing is stored
                      // (and never needed for keyless ollama).
}

{ "ok": false, "error": "healthcheck is only supported for the native runtime" }

{ "ok": false, "error": "unknown provider '<provider>'" }

{ "ok": false, "error": "apiKey is required" }

{ "ok": true }

{ ok: false, error: 'Invalid API key.' }            // 401/403 from the provider
{ ok: false, error: 'Provider returned <status>.' } // other non-2xx
{ ok: false, error: 'Could not reach <provider> (timed out).' } // 8s abort
{ ok: false, error: 'Could not reach <provider>.' }            // network error

curl -X POST http://localhost:18790/api/runtimes/clawboo-native/healthcheck \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-..."}'

{
  taskId: string                    // required
  assigneeAgentId?: string          // default = the runtime id; must match /^[A-Za-z0-9_-]+$/
  repoPath?: string | null          // git repo to branch the worktree from
  kind?: string                     // task kind → isolation; default 'code'
  model?: string | null             // model override for the run
  keepForResume?: boolean           // pause-for-handoff: keep worktree + release task
  disableMemoryAutoInject?: boolean // skip run-start memory injection
  maxRotations?: number             // bound the session-rotation chain
  breakerConfig?: object            // per-run circuit-breaker overrides (zod-validated; ignored if invalid)
  parentTraceparent?: string | null // W3C traceparent to nest this run's trace
}

{ "error": "taskId is required" }

{ "error": "invalid assigneeAgentId" }

{
  ok: true
  runtimeId: string
  execId: string
  doneReason: 'success' | 'max_turns' | 'aborted' | 'error'
  status: string
  summary: string
  costUsd: number | null
  usedWorktree: boolean
  degradations: string[]
}

{ "ok": false, "reason": "not_found" }

{ "ok": false, "reason": "conflict" }

{ ok: false, reason: 'too_deep' | 'connected_substrate' | 'budget_paused' }

{ "error": "<message>" }

curl -X POST http://localhost:18790/api/runtimes/claude-code/run \
  -H 'Content-Type: application/json' \
  -d '{"taskId":"<task-uuid>","repoPath":"/path/to/repo","kind":"code"}'

{
  models: Array<{ id: string; label: string }>
}

curl http://localhost:18790/api/runtimes/openrouter/models

{
  provider?: string  // 'anthropic' | 'openai' | 'openrouter' | 'ollama' |
                     // 'google' | 'xai' | 'groq' | 'mistral' | 'together' |
                     // 'cerebras' | 'moonshot'; default 'anthropic'
  model?: string     // optional leader-model override (the specialist keeps its default)
}

{ "error": "unknown provider '<provider>'" }

{ teamId: string, leaderAgentId: string, specialistAgentId: string }

{ "error": "<message>" }

curl -X POST http://localhost:18790/api/onboarding/seed-native-team \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic"}'

{
  configured: boolean // OpenClaw installed + `openclaw.json` + `.env` present
  hasNative: boolean // at least one `clawboo-native` agent row
  hasTeam: boolean // at least one team row
  hasConnectedRuntime: boolean // see below
}

{ "error": "unknown login tool: <tool>" }

curl -N -X POST http://localhost:18790/api/auth/cli-login/codex