CLI Runtime API

CLI runtimes let a Pioneer turn run through a local CLI-backed agent process instead of a direct model API provider. The current committed runtime implementation is Codex CLI through pioneer-cli-agent-runtime; the protocol enum also reserves a claude kind for future or in-progress runtime work. CLI runtimes are not pioneer-provider adapters. API providers expose provider/* methods. CLI runtimes expose cli_runtime/* methods and are selected as an execution backend on turn/start.

Methods

Method	Params	Result	Purpose
`cli_runtime/list`	`CLIRuntimeListParams`	`CLIRuntimeListResponse`	List configured runtime instances for a workspace.
`cli_runtime/get`	`CLIRuntimeGetParams`	`CLIRuntimeGetResponse`	Return one runtime summary.
`cli_runtime/status`	`CLIRuntimeStatusParams`	`CLIRuntimeStatusResponse`	Return cached status for one runtime.
`cli_runtime/refresh`	`CLIRuntimeRefreshParams`	`CLIRuntimeRefreshResponse`	Probe one or all runtimes and return live summaries.
`cli_runtime/list_models`	`CLIRuntimeListModelsParams`	`CLIRuntimeListModelsResponse`	List models available through a runtime.
`cli_runtime/thread_binding/get`	`CLIRuntimeThreadBindingGetParams`	`CLIRuntimeThreadBindingGetResponse`	Read the native CLI thread binding for a Pioneer thread.
`cli_runtime/thread/fork`	`CLIRuntimeThreadForkParams`	`CLIRuntimeThreadForkResponse`	Fork a runtime-native thread into a new Pioneer thread.
`cli_runtime/thread/compact`	`CLIRuntimeThreadCompactParams`	`CLIRuntimeThreadCompactResponse`	Ask the runtime to compact a bound native thread.
`cli_runtime/turn/steer`	`CLIRuntimeTurnSteerParams`	`CLIRuntimeTurnSteerResponse`	Send steering text to an active runtime-backed turn.
`cli_runtime/review/start`	`CLIRuntimeReviewStartParams`	`CLIRuntimeReviewStartResponse`	Start a runtime-native review flow for changes, a branch, a commit, or custom instructions.
`cli_runtime/login/start`	`CLIRuntimeLoginStartParams`	`CLIRuntimeLoginStartResponse`	Start a supported runtime login flow.
`cli_runtime/login/cancel`	`CLIRuntimeLoginCancelParams`	`CLIRuntimeLoginCancelResponse`	Cancel a pending runtime login flow.
`cli_runtime/proxy/set`	`CLIRuntimeProxySetParams`	`CLIRuntimeProxySetResponse`	Set the workspace-scoped network proxy for a runtime.
`cli_runtime/proxy/delete`	`CLIRuntimeProxyDeleteParams`	`CLIRuntimeProxyDeleteResponse`	Remove the runtime proxy.
`cli_runtime/request/respond`	`CLIRuntimeRequestRespondParams`	`CLIRuntimeRequestRespondResponse`	Resolve a pending approval or user-input request from the runtime.

Every method takes workspace_id. Runtime visibility is gateway-owned, but clients use the workspace id so responses and notifications can be scoped to the selected workspace.

Runtime summary

A RuntimeSummary includes:

Field	Meaning
`runtime_id`	Stable gateway runtime id, for example `codex`.
`kind`	Runtime kind, currently `codex` in committed config.
`display_name`	Human-readable label for model selectors and settings UI.
`enabled`	Whether the runtime instance is enabled.
`status`	Tagged status such as `ready`, `needs_auth`, `missing_binary`, `degraded`, or `unsupported_version`.
`capabilities`	Booleans for threads, resume, fork, steer, approvals, model list, review, compaction, auth management, and related features.
`account`	Optional authenticated account snapshot.
`version`, `binary_path`, `home_path`, `shadow_home_path`	Runtime installation and home details.
`diagnostics`, `recent_stderr`	Sanitized diagnostic lines for UI/debug surfaces.

Diagnostics are sanitized before they cross the protocol boundary. Secret-like keys, bearer tokens, raw payloads, and long lines are redacted or truncated. capabilities.supports_mcp_tools means the runtime can receive the gateway’s selected MCP projection for a turn. It does not mean every configured server or tool is available: workspace policy, turn permissions, provider support, catalog state, readiness, and the shared MCP limits still apply. Clients should use the capability flag as an eligibility signal and render the actual accepted or rejected capability results from the turn projection.

Listing runtimes

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "cli_runtime/list",
  "params": {
    "workspace_id": "ws_000000000000000001"
  }
}

Response shape:

{
  "runtimes": [
    {
      "runtime_id": "codex",
      "kind": "codex",
      "display_name": "Codex CLI",
      "enabled": true,
      "status": { "state": "ready" },
      "capabilities": {
        "supports_threads": true,
        "supports_resume": true,
        "supports_fork": true,
        "supports_steer": true,
        "supports_interrupt": true,
        "supports_approvals": true,
        "supports_file_change_approvals": true,
        "supports_command_approvals": true,
        "supports_user_input_requests": true,
        "supports_model_list": true,
        "supports_apps": false,
        "supports_review": true,
        "supports_compaction": true,
        "supports_goal": true,
        "supports_diff_updates": true,
        "supports_history_read": true,
        "supports_thread_archive": true,
        "supports_auth_management": true,
        "supports_generated_schema_probe": true,
        "supports_mcp_tools": true
      }
    }
  ]
}

Clients should use the generated schema and treat unknown future capability flags conservatively.

Runtime proxy

CLI runtime processes run on the gateway host. When a runtime needs a different egress route, configure its proxy with cli_runtime/proxy/set. The gateway validates and stores the URL for the selected workspace and runtime, passes it to runtime startup and account/MCP readiness probes, and exposes the configured value in sanitized runtime status. Use cli_runtime/proxy/delete to remove it. Proxy credentials belong in the gateway secret store; clients should never log or echo them.

Model selection

Clients can merge API providers and CLI runtimes in one model selector. The mobile client represents CLI runtime provider rows with the synthetic provider key:

cli_runtime:<runtime_id>

When the user selects such a row, fetch models with cli_runtime/list_models, then start turns with execution_backend set to cliAgentRuntime.

{
  "method": "cli_runtime/list_models",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "runtime_id": "codex"
  }
}

Starting a CLI runtime turn

turn/start can select the runtime explicitly:

{
  "method": "turn/start",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "mode": "Agent",
    "model": "gpt-5.4",
    "execution_backend": {
      "type": "cliAgentRuntime",
      "runtime_id": "codex",
      "runtime_kind": "codex"
    },
    "permission_profile": {
      "mode": "supervised"
    },
    "cli_runtime_options": {
      "effort": "high",
      "personality": "concise"
    },
    "input": [
      {
        "type": "text",
        "text": "Review the uncommitted changes.",
        "textElements": []
      }
    ]
  }
}

permission_profile is the Pioneer-level permission mode. The gateway resolves it into the turn security snapshot and maps it into the runtime-specific approval/sandbox policy before starting the native runtime turn. For Codex, full_access maps to never, supervised maps to on-request, and auto_accept_edits currently uses on-request as a stricter fallback. For Claude-style runtimes, full_access maps to bypassPermissions, auto_accept_edits maps to acceptEdits, and supervised maps to default. cli_runtime_options remains runtime-specific for options such as sandbox, effort, personality, summary, and steer_if_active. Clients should not send a separate runtime approval policy here; use permission_profile so Pioneer can persist one permission profile and audit model for the turn.

Thread binding and steering

When a Pioneer thread is backed by a native runtime thread, the gateway stores a CLIRuntimeThreadBinding with the Pioneer thread id, runtime id, native thread id, optional native cwd/model, and binding status. Clients can read the binding with:

{
  "method": "cli_runtime/thread_binding/get",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "thread_id": "thr_000000000000000001"
  }
}

If the runtime supports steering and the thread has an active turn, send:

{
  "method": "cli_runtime/turn/steer",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "runtime_id": "codex",
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "message": "Focus only on the API boundary and ignore formatting."
  }
}

Pending requests

CLI runtimes can ask the user to approve commands, approve file changes, or provide input. The gateway publishes:

Event	Meaning
`cli_runtime/request_opened`	A pending runtime request is ready for client UI.
`cli_runtime/request_resolved`	The request no longer needs user action.

Request kinds include command_approval, file_change_approval, user_input, and other. Resolve a request with:

{
  "method": "cli_runtime/request/respond",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "runtime_id": "codex",
    "request_id": "req_000000000000000001",
    "resolution": {
      "status": "approved"
    }
  }
}

Other resolutions are denied, cancelled, answered, expired, and error. These are runtime-native pending requests. Native Pioneer tool permission prompts use turn/permission/request/opened, turn/permission/request/respond, and turn/permission/request/resolved; see Turns API.

Notifications

CLI runtime notifications are:

Event	Params	Meaning
`cli_runtime/status_changed`	`CLIRuntimeStatusChangedNotification`	Runtime status or diagnostics changed.
`cli_runtime/account_updated`	`CLIRuntimeAccountUpdatedNotification`	Runtime authentication/account snapshot changed.
`cli_runtime/request_opened`	`CLIRuntimeRequestOpenedNotification`	User action is required for a runtime request.
`cli_runtime/request_resolved`	`CLIRuntimeRequestResolvedNotification`	A pending runtime request was resolved.
`cli_runtime/apps_changed`	`CLIRuntimeAppsChangedNotification`	Runtime app catalog changed.
`cli_runtime/generated_schema_probe`	Runtime schema probe result	The gateway completed a generated-schema capability probe; use it as diagnostics, not as a replacement for the typed capability flags.

Settings

Configured CLI runtime instances are exposed through settings/get under settings.cli_runtimes.instances. Updating settings.cli_runtimes replaces the runtime instance list stored in gateway-settings.toml. Operator defaults can also come from app config under [gateway.cli_agent_runtime] and [gateway.cli_agent_runtimes.<id>]. User-facing clients should prefer settings/get and settings/update for runtime changes.

Schemas

Generated schemas include:

/schemas/agent_execution_backend.json
/schemas/turn_cli_runtime_options.json
/schemas/runtime_summary.json
/schemas/runtime_status.json
/schemas/runtime_capabilities.json
/schemas/runtime_model_info.json
/schemas/cli_runtime_list_params.json
/schemas/cli_runtime_list_response.json
/schemas/cli_runtime_list_models_params.json
/schemas/cli_runtime_list_models_response.json
/schemas/cli_runtime_thread_binding.json
/schemas/cli_runtime_turn_steer_params.json
/schemas/cli_runtime_request_respond_params.json

CLI Runtime Architecture explains session management, native thread/turn bindings, pending requests, and restart recovery.
Permission System explains how Pioneer permission modes and security snapshots map into CLI runtime approval and sandbox policies.
Provider System explains why CLI-backed runtimes are separate from API provider adapters.
Client Architecture explains how desktop and mobile consume runtime projections.

Introduction

Workspace & Threads

Features

CLI Runtime API

Methods

Runtime summary

Listing runtimes

Runtime proxy

Model selection

Starting a CLI runtime turn

Thread binding and steering

Pending requests

Notifications

Settings

Schemas

​Methods

​Runtime summary

​Listing runtimes

​Runtime proxy

​Model selection

​Starting a CLI runtime turn

​Thread binding and steering

​Pending requests

​Notifications

​Settings

​Schemas

​Related pages

Methods

Runtime summary

Listing runtimes

Runtime proxy

Model selection

Starting a CLI runtime turn

Thread binding and steering

Pending requests

Notifications

Settings

Schemas

Related pages