> ## Documentation Index > Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt > Use this file to discover all available pages before exploring further. # CLI Runtime API > Listing CLI agent runtimes, selecting runtime models, binding Pioneer threads to native CLI threads, steering turns, handling approvals, and login flow. 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 ```json theme={null} { "jsonrpc": "2.0", "id": "aaaaaaaaaaaaaaaaaaaaa", "method": "cli_runtime/list", "params": { "workspace_id": "ws_000000000000000001" } } ``` Response shape: ```json theme={null} { "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: ```text theme={null} cli_runtime: ``` When the user selects such a row, fetch models with `cli_runtime/list_models`, then start turns with `execution_backend` set to `cliAgentRuntime`. ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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](/protocol/turns). ## 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.]`. 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` ## Related pages * [CLI Runtime Architecture](/architecture/cli-runtime) explains session management, native thread/turn bindings, pending requests, and restart recovery. * [Permission System](/architecture/permissions) explains how Pioneer permission modes and security snapshots map into CLI runtime approval and sandbox policies. * [Provider System](/architecture/providers) explains why CLI-backed runtimes are separate from API provider adapters. * [Client Architecture](/architecture/clients) explains how desktop and mobile consume runtime projections.