Initialize Server

Initialize a dormant server with runtime configuration.

Returns 400 if the server has already been initialized (state != dormant). Returns 500 if initialization fails; in that case the state rolls back to dormant so the orchestrator can retry.

POST /api/init

Initialize Server

cURL

curl --request POST \
  --url https://api.example.com/api/init \
  --header 'Content-Type: application/json' \
  --header 'X-Session-API-Key: <api-key>' \
  --data '
{
  "allow_cors_origins": [
    "<string>"
  ],
  "bash_events_dir": "<string>",
  "conversation_worktree_root": "<string>",
  "conversations_path": "<string>",
  "env": {},
  "max_concurrent_runs": 2,
  "secret_key": "<string>",
  "session_api_keys": [
    "<string>"
  ],
  "telemetry": {
    "deployment_kind": "local",
    "event_buffer_size": 20,
    "exporter": "none",
    "flush_delay": 30,
    "http_endpoint": "<string>",
    "http_token": "<string>",
    "max_queue_size": 1000,
    "num_retries": 2,
    "posthog_api_key": "<string>",
    "posthog_host": "https://us.i.posthog.com",
    "retry_delay": 5,
    "salt": "<string>"
  },
  "web_url": "<string>",
  "webhooks": [
    {
      "base_url": "<string>",
      "event_buffer_size": 5,
      "flush_delay": 30,
      "headers": {},
      "max_batch_bytes": 5242880,
      "max_queue_bytes": 52428800,
      "max_queue_size": 1000,
      "num_retries": 3,
      "retry_delay": 5
    }
  ]
}
'

200

{
  "state": "dormant",
  "error": "<string>"
}

Authorizations

X-Session-API-Key · string · header · required

Body

application/json

Runtime configuration delivered at /api/init time.

Each field is optional and overrides the equivalent field on the dormant Config. Fields not provided keep the value the server was constructed with (typically from env vars at pod startup). The set of overridable fields is intentionally narrow — it covers the values that today are "env-var shaped" and must change per-user, not image-build-time configuration (Python deps, plugin set, etc.) which stays bound to the warm-pool flavor.

allow_cors_origins · string[] | null

CORS origins to add to the existing localhost allowlist.

bash_events_dir · string<path> | null

Directory where bash events are persisted. Typically located inside the mounted user workspace.

conversation_worktree_root · string<path> | null

Root directory for conversation git worktrees. Override this to point at the mounted user workspace.

conversations_path · string<path> | null

Directory where conversations are persisted. Override this to point at the mounted user workspace.

env · Env · object | null

Process environment variables to set before conversation services start. Useful for credentials consumed by tools (e.g. GITHUB_TOKEN). These are applied with os.environ.update; existing values are overwritten.

Show child attributes

max_concurrent_runs · integer | null

Override the conversation-step concurrency limit.

Required range: x >= 1

secret_key · string<password> | null

Symmetric secret used to encrypt persisted secrets. If not provided, falls back to the first session_api_key (matching the default Config behavior).

session_api_keys · string[] | null

Per-user session API keys. If provided, all subsequent /api/* requests must authenticate with one of these keys via the X-Session-API-Key header.

telemetry · TelemetrySpec · object | null

Product-analytics policy for this pod. Without this, a warm-pool pod keeps whatever mode it booted with (normally 'disabled'), so a deployment that expects telemetry must supply it here.

Show child attributes

web_url · string | null

External URL where this server is reachable, used for root-path calculation. Only honored when not already set in dormant config.

webhooks · WebhookSpec · object[] | null

Per-user webhooks (e.g. for streaming events back).

Show child attributes

Response

200

application/json

Successful Response

state · enum<string> · required

dormant — server is up but waiting for /api/init. initializing — /api/init has been received and services are starting. ready — initialization complete; all /api/* routes are live.

Available options: dormant, initializing, ready

error · string | null

If a previous /api/init attempt failed, the error message. The state rolls back to dormant so /api/init can be retried.