Agent Worker API

The agent-worker API is internal — runners call it, not user applications. The endpoints below apply to inbound server mode. In outbound client mode, the worker binds no port and calls the runner instead.

Transport Modes

Inbound server mode remains the default. When both ORCA_RUNNER_URL and ORCA_WORKER_TOKEN are set, the same process switches to a session-scoped outbound client. ORCA_SESSION_ID is then required. The outbound client uses three runner endpoints, all authenticated with Authorization: Bearer <ORCA_WORKER_TOKEN>:

Method and path	Purpose
`GET /worker/sessions/{id}/next-run`	Long-poll for `run`, `export_state`, or `shutdown` commands. `204` means no work.
`POST /worker/sessions/{id}/events`	Upload the active run’s NDJSON event stream. `X-Orca-Run-Id` identifies the run; closing the upload cancels it.
`POST /worker/sessions/{id}/state`	Upload an opaque runtime state bundle with `Content-Type` and `X-Runtime-Session-Id`.

The worker sends X-Orca-Worker-Protocol: 1 when polling. It writes state to ORCA_STATE_DIR after each run and on export_state, uploads a durable copy to the runner, and restores the disk copy before its first poll. These state operations are best-effort so a corrupt or unavailable bundle does not prevent the worker from calling home.

Base URL

In inbound server mode, sidecars run on configurable ports (default 7070). In a typical setup:

Sidecar	Port
`MODE=claude`	7071
`MODE=codex`	7072
`MODE=general`	7073
`MODE=all` (poly)	7070

Health Check

GET /health

Returns sidecar health, the active runtime mode, and the identity and self-reported footprint of this worker process. /healthz returns the same body.

curl http://sidecar:7071/health

{
  "ok": true,
  "runtime": "claude",
  "instanceId": "worker-a1b2c3d4",
  "pid": 42,
  "startedAt": "2026-04-25T10:00:00.000Z",
  "uptimeSeconds": 3600,
  "inflight": 1,
  "nodeVersion": "v24.9.0",
  "memory": {
    "rssBytes": 80000000,
    "heapUsedBytes": 30000000,
    "heapTotalBytes": 50000000,
    "externalBytes": 2000000
  },
  "cpu": { "userMicros": 1200000, "systemMicros": 300000 }
}

The response also includes the X-Orca-Worker-Instance header. The ID is generated once per process and changes when the process restarts. POST /run responses include the same X-Orca-Worker-Instance header and an X-Orca-Worker-Inflight header containing the process’s in-flight run count at the start of the response. The runner uses the identity header for passive instance observation, while it obtains memory and CPU details from /health probes.

Run Execution

POST /run

Executes a task against the configured LLM provider. Returns a streaming NDJSON response of RunEvent objects. Request body:

{
  "sessionId": "sess-a1b2c3d4-e5f6g7h8",
  "profile": {
    "name": "researcher",
    "runtime": "general",
    "systemPrompt": "You are a research assistant.",
    "tools": ["web_search", "time_now"],
    "model": "anthropic:claude-sonnet-4-6"
  },
  "subtask": {
    "title": "Research task",
    "prompt": "What are the top AI agent frameworks?",
    "files": []
  },
  "sessionMcpUrl": "http://runner:7070/runner/sessions/sess-.../mcp",
  "skills": [],
  "mcpServers": [
    {
      "name": "my-api",
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer resolved-secret" }
    }
  ]
}

Request fields:

Field	Type	Required	Description
`sessionId`	string	✓	Session identifier
`profile.name`	string	✓	Profile name
`profile.runtime`	string	✓	`claude`, `codex`, or `general`
`profile.systemPrompt`	string	—	System instructions
`profile.tools`	string[]	—	Tool allowlist
`profile.model`	string	—	LLM model identifier
`subtask.title`	string	✓	Short label
`subtask.prompt`	string	✓	Task description
`subtask.files`	string[]	—	File references
`sessionMcpUrl`	string	✓	Runner’s MCP endpoint for this session
`skills`	object[]	—	Pre-resolved active skill bodies and resource manifests for this run
`mcpServers`	object[]	—	Additional external MCP servers

Response: application/x-ndjson (streaming) If run dispatch fails after the streaming response has started, the sidecar writes a terminal error event and closes the stream; the process remains available for subsequent runs. Each line is a RunEvent JSON object:

{"type":"progress","message":"Starting run...","ts":"..."}
{"type":"session","runtimeSessionId":"sdk-session-or-thread-id","ts":"..."}
{"type":"assistant","message":"I'll look this up...","ts":"..."}
{"type":"tool_call","toolCallId":"call_abc","toolName":"web_search","input":{"query":"..."},"ts":"..."}
{"type":"tool_result","toolCallId":"call_abc","toolName":"web_search","output":{"results":[...]},"isError":false,"ts":"..."}
{"type":"assistant","message":"Based on my research...","ts":"..."}
{"type":"result","message":"Final answer...","ts":"..."}
{"type":"usage","usage":{"inputTokens":1240,"outputTokens":380},"ts":"..."}

RunEvent Schema

interface RunEvent {
  type: "progress" | "assistant" | "tool_call" | "tool_result" | "usage" | "session" | "result" | "error";
  message?: string;           // for progress, assistant, result, error
  runtimeSessionId?: string;  // for session; Claude session_id or Codex thread_id
  toolCallId?: string;        // for tool_call, tool_result
  toolName?: string;          // for tool_call, tool_result
  input?: unknown;            // tool input (tool_call)
  output?: unknown;           // tool output (tool_result)
  isError?: boolean;          // error flag (tool_result)
  usage?: {
    inputTokens: number;
    outputTokens: number;
    cacheReadTokens?: number;
    cacheCreateTokens?: number;
  };
  ts: string;                 // ISO 8601
}

Session State

GET /state/:sessionId

Exports an opaque state bundle for one sidecar session. Runners use this internal route when they need to persist runtime-local conversation state outside the sidecar process.

curl http://sidecar:7071/state/sess-a1b2c3d4-e5f6g7h8

When MODE=all, pass the runtime explicitly:

curl 'http://sidecar:7070/state/sess-a1b2c3d4-e5f6g7h8?runtime=claude'

Response headers:

Header	Description
`Content-Type`	`application/json` for `general`; `application/gzip` for `claude` and `codex`
`X-Runtime-Session-Id`	Runtime-native conversation handle, such as a Claude SDK `session_id` or Codex `thread_id`

Returns 400 for malformed percent-encoding in sessionId or, in MODE=all, a missing or unknown runtime query parameter. Returns 404 when the sidecar has no exportable state for the session. Codex exports include only rollout files whose filename contains the exact requested thread ID at ID-token boundaries; a thread ID like thread-1 does not also export thread-12.

POST /state/:sessionId

Hydrates a sidecar session from a previously exported state bundle. The request body is treated as the exported body for that runtime: JSON for general, gzip state bundles for claude and codex.

curl -X POST http://sidecar:7071/state/sess-a1b2c3d4-e5f6g7h8 \
  -H 'Content-Type: application/gzip' \
  -H 'X-Runtime-Session-Id: sdk-session-or-thread-id' \
  --data-binary @state-bundle.tgz

When MODE=all, pass the runtime query parameter. On success, the sidecar returns 204 No Content; the next POST /run for that session can resume from the hydrated state. Client-caused import failures, such as invalid JSON or corrupt gzip/tar data, return 400 and do not seed X-Runtime-Session-Id for the session. Unexpected dispatcher failures return 500; the sidecar contains the error and continues serving subsequent requests.

Mode Configuration

The sidecar’s behavior is controlled by the MODE environment variable:

claude
codex
general
all (poly)

Uses @anthropic-ai/claude-agent-sdk.

MODE=claude \
PORT=7071 \
ANTHROPIC_API_KEY=sk-ant-... \
node src/server.js

Model format: claude-sonnet-4-6, claude-haiku-4-5Host-executing Claude built-ins are disabled by default. Use runner MCP tools for filesystem, sandbox, and skill-script execution.

Uses @openai/codex-sdk.

MODE=codex \
PORT=7072 \
OPENAI_API_KEY=sk-... \
node src/server.js

Model format: codex-mini, o4-miniCodex runs with sandboxMode: "read-only" by default. It does not receive host write/exec access unless the break-glass AGENT_WORKER_ALLOW_HOST_TOOLS=1 is set.

Uses Vercel AI SDK with multi-provider support.

MODE=general \
PORT=7073 \
ANTHROPIC_API_KEY=sk-ant-... \
OPENAI_API_KEY=sk-... \
node src/server.js

Model format: anthropic:claude-sonnet-4-6, openai:gpt-5.2, google:gemini-2.5-pro, groq:llama-3.3-70b-versatile

Dispatches to the appropriate mode based on profile.runtime.

MODE=all \
PORT=7070 \
ANTHROPIC_API_KEY=sk-ant-... \
OPENAI_API_KEY=sk-... \
node src/server.js

One process handles all runtimes.

Environment Variables

Variable	Default	Description
`PORT`	`7070`	HTTP listen port in inbound server mode
`MODE`	`general`	Runtime mode
`ORCA_RUNNER_URL`	—	Runner base URL. Together with `ORCA_WORKER_TOKEN`, enables outbound client mode.
`ORCA_WORKER_TOKEN`	—	Session-scoped bearer token required for outbound client mode.
`ORCA_SESSION_ID`	—	Orca session ID; required when outbound client mode is enabled.
`ORCA_WORKER_PROTOCOL`	`1`	Outbound worker protocol major. The worker rejects unsupported values at startup.
`ORCA_STATE_DIR`	`/var/orca/state`	Sandbox-disk checkpoint directory for outbound runtime state.
`ANTHROPIC_API_KEY`	—	Required for `claude` and Anthropic-backed `general`
`OPENAI_API_KEY`	—	Required for `codex` and OpenAI-backed `general`
`GOOGLE_GENERATIVE_AI_API_KEY`	—	Google Gemini models in `general` mode
`GROQ_API_KEY`	—	Groq models in `general` mode
`TAVILY_API_KEY`	—	Optional for sidecar-native modes; runner platform web tools need this on the runner
`AGENT_WORKER_STEP_COUNT`	`24`	Maximum Vercel AI SDK tool-call steps per request in `general` mode
`AGENT_WORKER_CHILD_ENV_ALLOW`	—	Comma-separated extra environment variable names to pass to spawned `claude` or `codex` children beyond the built-in allowlist
`AGENT_WORKER_ALLOW_HOST_TOOLS`	—	Break-glass only. Set to `1` to re-enable Claude host built-ins and Codex `danger-full-access`; unset keeps host tools disabled and routes execution through runner sandbox tools

MCP Bridge (general mode)

In general mode, the sidecar connects an MCP client to the runner’s session MCP endpoint: The sidecar also opens any external MCP servers from the profile and merges them with the runner platform tools. External tool names are prefixed separately from runner tool names. When a connected MCP catalog is large enough for deferred loading, general mode exposes search_tools and call_tool meta-tools instead of sending every underlying tool schema to the model on each turn. The deferred catalog stores plain JSON schemas only; Vercel AI SDK schema wrappers are unwrapped before search results are returned, and degenerate wrappers with no usable JSON schema fall back to {} so replayed history does not contain Symbol-keyed or function-valued schema metadata. The general mode sidecar keeps bounded in-memory session history for replay. If the upstream model stream errors after a turn has started, the sidecar commits the user prompt and any accumulated assistant/tool context once before emitting the terminal error event, so the next turn can replay the prior context. Replay also repairs malformed or partial tool-result history before handing messages back to the AI SDK, including defensive JSON sanitization that drops function-valued properties and replaces circular references with "[circular]".

Custom Sidecar

You can implement a custom sidecar that conforms to this API. Requirements:

GET /health → { ok: true, runtime: string }
POST /run → accepts the run envelope body, responds with NDJSON RunEvent stream
Must stream events as newline-delimited JSON
Must emit a result or error event to signal completion
For resumable sessions, implement GET /state/:sessionId and POST /state/:sessionId with opaque state-bundle bytes

This lets you integrate any LLM provider or custom inference engine with Orca’s orchestration layer.

​Transport Modes

​Base URL

​Health Check

​GET /health

​Run Execution

​POST /run

​RunEvent Schema

​Session State

​GET /state/:sessionId

​POST /state/:sessionId

​Mode Configuration

​Environment Variables

​MCP Bridge (general mode)

​Custom Sidecar

Transport Modes

Base URL

Health Check

GET /health

Run Execution

POST /run

RunEvent Schema

Session State

GET /state/:sessionId

POST /state/:sessionId

Mode Configuration

Environment Variables

MCP Bridge (general mode)

Custom Sidecar