Runner Wire API

The Runner wire API is internal. Applications should normally use the Conductor API.

Base URL

http://runner:7070

State-changing endpoints that do not return data use 204 No Content. Errors use:

{ "error": "message" }

Runner Info

Get Runner Info

Returns the runner identity used by the conductor pool.

curl http://runner:7070/runner/info

{
  "id": "runner-a1b2c3d4",
  "hash": "a1b2c3d4",
  "version": "dev",
  "startedAt": "2026-04-25T10:00:00Z",
  "capabilities": ["claude", "codex", "general"],
  "toolkitNames": ["echo", "list_dir", "math_add", "time_now"],
  "substrates": ["daytona", "e2b"],
  "defaultSubstrate": "daytona",
  "substratesKnown": true,
  "mcpBaseUrl": "http://runner-1:7070"
}

hash is SHA256(RUNNER_BASE_URL)[:8]. Session IDs embed this hash so any conductor can route a session back to its owning runner. substrates is the sorted set of worker substrates this runner can launch; defaultSubstrate is the one used when a sandbox-worker profile does not make an explicit choice. Read the list together with substratesKnown: true with an empty list means this runner definitively launches no workers, while an omitted or false value means an older runner did not report the capability.

Runtime Introspection

List Runtimes

Returns the runtime slots served by this runner, including how each slot is wired and its current process-wide session count:

{
  "runtimes": [
    {
      "id": "claude",
      "name": "claude",
      "mode": "sidecar",
      "url": "http://sidecar-claude:7071",
      "activeSessions": 3
    },
    {
      "id": "general",
      "name": "general",
      "mode": "stub",
      "url": "",
      "activeSessions": 0
    }
  ]
}

mode is sidecar when the runner is bound to an agent-worker base URL, stub when it uses the in-process adapter, or unknown when the runtime cannot expose its slot configuration. url is the configured sidecar base URL and is empty for stub slots; it may front multiple worker replicas and is not an instance identity. activeSessions counts live sessions resolved to that runtime across all tenants on the runner. Runtimes that cannot provide a cross-tenant session snapshot report 0.

Get Runner Topology

Returns an on-demand snapshot of the runner process, session counts by runtime, and the sidecar instances observed behind each configured runtime slot:

curl http://runner:7070/runner/topology

{
  "process": {
    "allocBytes": 18432000,
    "sysBytes": 25600000,
    "heapInuseBytes": 12000000,
    "numGoroutine": 42,
    "numCPU": 8,
    "uptimeSeconds": 86400
  },
  "sessionsByRuntime": { "claude": 3, "codex": 0, "general": 1 },
  "sidecars": [
    {
      "runtime": "claude",
      "mode": "sidecar",
      "endpoint": "http://sidecar-claude:7071",
      "state": "live",
      "activeSessions": 3,
      "observedInstances": [
        {
          "instanceId": "worker-a1b2c3d4",
          "firstSeenAt": "2026-04-25T10:00:00Z",
          "lastSeenAt": "2026-04-25T10:05:00Z",
          "runsServed": 12,
          "consecutiveFailures": 0,
          "lastProbedAt": "2026-04-25T10:04:55Z",
          "inflight": 1,
          "uptimeSeconds": 3600,
          "pid": 42,
          "nodeVersion": "v24.9.0",
          "memory": {
            "rssBytes": 80000000,
            "heapUsedBytes": 30000000,
            "heapTotalBytes": 50000000,
            "externalBytes": 2000000
          },
          "cpu": { "userMicros": 1200000, "systemMicros": 300000 }
        }
      ]
    }
  ]
}

sessionsByRuntime and each slot’s activeSessions are process-wide counts across tenants. Slot states are stub, live, cold, degraded, or unreachable: cold means a configured slot has no recent successful observation, while unreachable means its latest probe or transport attempt failed without a recent success. The runner observes instance IDs passively from run responses and probes a quiet sidecar endpoint’s /health endpoint on demand for process stats. An observedInstances list is therefore a lower bound on replicas behind the configured endpoint, not an exact fleet count; load-balancer connection pinning can leave running replicas unseen. Unprobed instance stats are null. When multiple runtime slots share one endpoint, as in a MODE=all poly sidecar, those slots report the same observed instances and health state and the endpoint is probed only once. Do not sum observedInstances across such slots: that would count the same worker processes multiple times.

Profiles

List Profiles

{ "profiles": [{ "name": "general", "runtime": "general" }] }

Create Profile

Conductors call this to seed or broadcast profile definitions.

{
  "profile": {
    "name": "researcher",
    "runtime": "general",
    "model": "anthropic:claude-sonnet-4-6",
    "tools": ["@default", "web_search", "web_extract"]
  }
}

Response: 204 No Content

Delete Profile

Pools

List Pools

{ "pools": [{ "name": "research-team", "members": [{ "profile": "researcher", "role": "lead" }] }] }

Create Pool

{
  "pool": {
    "name": "research-team",
    "members": [{ "profile": "researcher", "role": "lead" }]
  }
}

Delete Pool

Sessions

List Sessions

{
  "sessions": [
    {
      "id": "sess-a1b2c3d4-e5f6a7b8",
      "profile": "researcher",
      "runtime": "general",
      "status": 0,
      "createdAt": "2026-04-25T10:00:00Z",
      "lastUsedAt": "2026-04-25T10:00:00Z"
    }
  ]
}

Runner session status is the raw enum from types.SessionStatus: 0=idle, 1=running, 2=errored, 3=shutdown.

Create Session

{ "profileName": "researcher" }

Response 201 Created:

{ "sessionId": "sess-a1b2c3d4-e5f6a7b8" }

Get Session

{ "session": { "id": "sess-a1b2c3d4-e5f6a7b8", "profile": "researcher", "runtime": "general" } }

Session Health

{ "healthy": true }

When unhealthy, the response is still 200 OK with healthy: false and an error string.

List VFS Leases

Returns the active per-session VirtualFS leases on this runner. The response is always an array; runners without a VFS manager return [].

[
  {
    "sessionId": "sess-a1b2c3d4-e5f6a7b8",
    "allowedMounts": ["/agents", "/pools"],
    "allocatedAt": "2026-04-25T10:00:00Z"
  }
]

An empty allowedMounts array means the VirtualFS session is unrestricted.

Get Session VFS Lease

Returns the VirtualFS lease for one session.

{
  "sessionId": "sess-a1b2c3d4-e5f6a7b8",
  "allowedMounts": ["/agents"],
  "allocatedAt": "2026-04-25T10:00:00Z"
}

Returns 404 with { "error": "no vfs session" } when the session has no active VFS lease.

List Sandbox Worker Leases

Returns the per-session sandbox-worker leases owned by this runner. The conductor-facing alias is GET /api/worker/leases; in conductor mode it fans out across runners and may return partial results if a runner does not answer within the bounded lookup window. Deployments with no worker substrate, and deployments serving only static profiles, return []. Rows are sorted by sessionId on both planes. The broker’s lease map is keyed by session and iterated in map order, so the handler imposes the sort rather than trusting what the runtime returned; paging an unordered set would drop and repeat rows between requests. Tenant scoping. The result is scoped to the tenant on the request context, which the conductor verifies and forwards as X-Tenant-ID for runnerTenantMiddleware to restamp. A request with no tenant on context is the internal/admin fan-out and still sees every lease. GET /api/sessions/{id}/worker scopes the same way and answers 404 for another tenant’s session, matching the 404 a static-profile session already returns so it reveals nothing about whether the id exists. Pagination. The /api/* alias honors ?limit= and ?offset= and sets X-Total-Count to the caller’s full (tenant-scoped) lease count. The /runner/* path is deliberately not paginated: the conductor’s fan-out reads it whole before merging, and a default window there would silently truncate a busy runner and make the merged fleet total wrong.

[
  {
    "sessionId": "sess-a1b2c3d4-e5f6a7b8",
    "substrate": "daytona",
    "workerId": "sandbox-7f90c2",
    "runtime": "general",
    "state": "running",
    "startedAt": "2026-08-14T10:00:00Z"
  }
]

state is one of starting, running, paused, gone, or unknown, read live from the substrate so it reflects a sandbox stopped or deleted outside Orca. paused is the normal resting state of an idle session and resumes with its conversation intact; gone means the next run launches a replacement worker without it. unknown means the substrate could not be reached, which is not the same as gone. It describes the lease, not worker-process health. A substrate can keep a sandbox available after the worker exits so its diagnostic log can be read.

Get Session Sandbox Worker

Returns one sandbox-worker lease using the same schema. The conductor-facing alias is GET /api/sessions/{sessionId}/worker. A static-profile session, an unknown session, or a sandbox-worker session before its first run returns 404 with { "error": "no sandbox worker" }. An upstream runner failure returns 502.

Delete Session

Shuts down the session and its scoped MCP endpoint.

Hydrate Session

Recreates a session under a caller-supplied id after a runner restart. The conductor uses this to restore the runner record and, when present, push an opaque sidecar state bundle back into the runtime.

{
  "profileName": "researcher",
  "runtimeSessionId": "sdk-session-or-thread-id",
  "stateContentType": "application/gzip",
  "stateB64": "H4sIAAAAA..."
}

stateB64 is optional and carries the exported state bundle as base64. The endpoint is idempotent: if the session already exists on that runner, the hydrate request is a no-op. Response: 204 No Content Returns 400 when the request body fails to decode or stateB64 is not valid base64. Returns 404 when profileName does not match a profile known to this runner, or when sessionId is already in use by a session that belongs to a different tenant.

Export Session State

Exports the sidecar’s opaque state bundle for the session. The response body is the raw bundle, with the envelope carried in headers:

Header	Description
`Content-Type`	Bundle media type, such as `application/gzip`
`X-Runtime-Session-Id`	Runtime-native conversation handle, such as a Claude SDK `session_id` or Codex `thread_id`

Returns 404 when the session is unknown or the sidecar has no exportable state. Export failures such as sidecar 5xx responses, transport errors, or bundles over the runner size cap return 500 so clients do not mistake them for a missing bundle.

Run Execution

Execute Run

The conductor calls this action endpoint on the runner that owns the session. The response is an NDJSON stream of run events.

{
  "subTask": {
    "id": "run-f3a9b72c",
    "parentId": "run-parent",
    "profile": "researcher",
    "sessionId": "sess-a1b2c3d4-e5f6a7b8",
    "title": "Research task",
    "prompt": "What is the capital of France?",
    "files": []
  }
}

Response: application/x-ndjson

{"type":"progress","message":"Starting run..."}
{"type":"session_init","runtimeSessionId":"sdk-session-or-thread-id"}
{"type":"assistant","message":"The capital of France is Paris."}
{"type":"result","message":"Paris"}
{"type":"usage","usage":{"inputTokens":42,"outputTokens":8}}

Event types are progress, session_init, assistant, tool_call, tool_result, usage, result, and error.

Toolkit

List Global Toolkit

Returns every platform tool registered in the runner process.

{
  "specs": [
    {
      "name": "time_now",
      "description": "Current wall-clock time in an optional IANA timezone (default UTC).",
      "inputSchema": { "type": "object" },
      "scope": "platform",
      "capability": "introspection"
    }
  ]
}

List Session Toolkit

Returns the profile-scoped toolkit for one session. Unknown sessions return 404.

Invoke Session Tool

Executes a tool through the session-scoped registry. Out-of-scope tools return 403 even if the runner hosts that tool globally.

{
  "toolName": "math_add",
  "input": { "a": 2, "b": 3 }
}

Response 200 OK:

{
  "result": {
    "ok": true,
    "value": { "sum": 5 }
  }
}

Tool-level failures also return 200 OK with result.ok: false; non-200 responses are wire-level errors such as bad JSON, missing session, or an out-of-scope tool.

Sandbox Worker Callback API

Profiles with workerMode: "sandbox" use an outbound-only worker. Every request below requires Authorization: Bearer <ORCA_WORKER_TOKEN>. The runner verifies that the token’s tenant and session claims match the requested session.

Method and path	Behavior
`GET /worker/sessions/{sessionId}/next-run`	Long-polls for a protocol v1 `run`, `export_state`, or `shutdown` command. Returns `204` after an idle poll timeout.
`POST /worker/sessions/{sessionId}/events`	Uploads NDJSON run events. `X-Orca-Run-Id` must match the active command; stale or cancelled uploads return `409`. One line may be at most 4 MiB, the complete upload at most 256 MiB, and one upload may remain open for at most 4 hours.
`POST /worker/sessions/{sessionId}/state`	Uploads the latest opaque state bundle. `Content-Type` and `X-Runtime-Session-Id` carry its envelope.

Missing, invalid, expired, or session-mismatched tokens return 401. The JSON error keeps the invalid or missing worker token prefix and identifies whether the request had no token, the service has no usable key, the token expired or is malformed, its session does not match, or the signer and verifier disagree. Unknown sessions return 404, and runners without the dynamic-worker runtime surface return 503. An event upload over 256 MiB returns 413; one that exceeds 4 hours returns 408. Either condition ends the event stream with an error so the run fails instead of appearing to finish with truncated output. State uploads use the runner’s existing state-bundle size cap and return 413 when exceeded.

ORCA_WORKER_TOKEN and the orca_worker_token query parameter embedded in a sandbox worker’s session MCP URL are bearer credentials. Do not write them to logs, traces, or error messages. The worker token has a 24-hour lifetime; the MCP query token is minted per run and normally lasts 2 hours when the run has no deadline. A run deadline replaces that default with the remaining time plus 5 minutes of grace, subject to a 5-minute floor and the runner’s 24-hour signing ceiling.

Sandbox Event Invalidation (Internal)

The conductor uses this runner-internal route after decoding a provider event. It accepts { "provider": "daytona", "sandboxId": "..." }, marks matching worker-lease status caches stale, and returns { "invalidated": 1 }. A zero count is normal when this runner does not own the provider-scoped sandbox ID. Keep this route on the trusted runner network; unlike the public provider ingress, it accepts an already-decoded event.

Session MCP Endpoint

The runner exposes a streamable-HTTP MCP server per session. Sidecars use the URL advertised in the run envelope, and external MCP clients can connect directly when they can reach the runner. Sandbox-worker sessions require their session-scoped worker token; static-sidecar sessions retain the existing unauthenticated runner-network behavior. When an MCP base URL is configured for a sandbox session, the runner refuses to dispatch the run if its signing key is unavailable, token minting fails, or the minter returns an empty token. The run error names the signing configuration or mint failure instead of advertising a bare capability URL that would fail later with 401.

curl -X POST http://runner:7070/runner/sessions/sess-a1b2c3d4-e5f6a7b8/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

The MCP surface maps to the same session-scoped toolkit as /toolkit/specs and /toolkit/invoke.

Health & Metrics

Health Check

Returns text/plain ok.

Prometheus Metrics

Returns Prometheus text format metrics from the runner process.

​Base URL

​Runner Info

​Get Runner Info

​Runtime Introspection

​List Runtimes

​Get Runner Topology

​Profiles

​List Profiles

​Create Profile

​Delete Profile

​Pools

​List Pools

​Create Pool

​Delete Pool

​Sessions

​List Sessions

​Create Session

​Get Session

​Session Health

​List VFS Leases

​Get Session VFS Lease

​List Sandbox Worker Leases

​Get Session Sandbox Worker

​Delete Session

​Hydrate Session

​Export Session State

​Run Execution

​Execute Run

​Toolkit

​List Global Toolkit

​List Session Toolkit

​Invoke Session Tool

​Sandbox Worker Callback API

​Sandbox Event Invalidation (Internal)

​Session MCP Endpoint

​Health & Metrics

​Health Check

​Prometheus Metrics

Base URL

Runner Info

Get Runner Info

Runtime Introspection

List Runtimes

Get Runner Topology

Profiles

List Profiles

Create Profile

Delete Profile

Pools

List Pools

Create Pool

Delete Pool

Sessions

List Sessions

Create Session

Get Session

Session Health

List VFS Leases

Get Session VFS Lease

List Sandbox Worker Leases

Get Session Sandbox Worker

Delete Session

Hydrate Session

Export Session State

Run Execution

Execute Run

Toolkit

List Global Toolkit

List Session Toolkit

Invoke Session Tool

Sandbox Worker Callback API

Sandbox Event Invalidation (Internal)

Session MCP Endpoint

Health & Metrics

Health Check

Prometheus Metrics