runtime-selection.mdx

title	Runtime selection
description	Select exactly one external CLI runtime for a run.

Runtime selection

agent-provider selects the executable runtime:

Value	Executable	Input mode
opencode	opencode	One positional prompt, explicit --model
codex	codex	Ephemeral stdin execution
cursor	agent	Non-interactive prompt mode

Only runtimes selected by active roles are provisioned, authenticated, and executed. A workflow may therefore use more than one runtime when its active roles have independent overrides. The runtime is not the model provider. For example, opencode can execute an openai/... model.

agent-executable and the corresponding role overrides may select only the expected bare basename or an absolute path with that basename. An explicit Windows path must end in the provider's exact native .exe basename; .cmd and .bat wrappers cannot be selected for no-shell execution. The canonical target must be a regular executable owned by the runner user or root and not group/world writable on Unix. On Windows, the executable, Node interpreter, and npm package entrypoint are checked read-only for trusted ownership and ACLs without untrusted write or ACL-control grants. An unreadable or unsafe ACL blocks that executable; Copilot does not rewrite installed files. The runtime manifest records historical smoke identities and official installation sources. A default runtime can be staged privately from its provider’s official source when missing, outdated, or rejected by the executable trust check; the runner's existing installation is never replaced or executed after rejection. An explicitly selected executable fails closed if unsafe and is never updated by the Action.

Codex no soportado en runners Windows ejecutados como servicio. This repository keeps the shared [self-hosted, codex] pool for macOS and Ubuntu; Windows service registrations omit codex. The Codex fixture matrix targets only those two supported platforms. General Windows fixtures remain separate. The limitation concerns session-0 services, not all Windows sessions or other agent runtimes. See Codex runtime support for observed failure and the distinction between model replies and real tool execution.

If agent preflight fails, the Action log identifies a fixed stage such as resolution, invocation-trust, or version. Private official installation failures report a closed stage, bounded exit code and, when recognizable, a fixed reason; they never print installer stderr, executable paths, prompts, arguments, or credentials. The standalone read-only CLI verifier checks trust once before its help, version, and optional login probes and retries only a transient Windows ACL query timeout once.

Codex child shells use private per-run application-data directories outside the checkout. The parent Codex login context is preserved; host profile paths and credentials remain excluded from child shells. Unexpected untracked files still block implementation rather than being ignored or committed.

Windows executable ACL checks run before the agent starts. Their PowerShell metadata probe uses only system modules and disables its own module cache, so missing service-account application-data variables cannot create Microsoft/Windows/PowerShell/ModuleAnalysisCache in the checkout. Official Windows installers also disable their PowerShell module cache before starting; this occurs before the provider's private shell policy exists. Executable and ancestor ACL validation remains mandatory.

Repository verification commands also receive a temporary Windows profile and module cache. Required Windows machine facts and the configured Jest worker recycling flag are preserved; operator profile paths and authentication-store references remain excluded.

On Windows, that verification home must also pass the existing private-directory and ancestor permission checks before it is used. Verification commands receive TMP, TEMP, TMPDIR and RUNNER_TEMP pointing to a private subdirectory of their temporary home. This keeps nested fixtures and installers in the same protected scope. The Action can fall back to a safe profile-local parent; it blocks execution when no safe parent is available and never changes host directory permissions.

The parent process and child shells also use an explicit PowerShell module-cache filename inside that private runtime directory. Ambient cache locations cannot redirect it into the checkout. Agent failures retain their specific timeout, cancellation, policy or execution code in the conversation reply. The agent's 15-minute deadline stays bounded; inspect the current state before retrying a timed-out implementation.

There is no runtime registry or provider fallback. The exhaustive dispatcher recognizes exactly these three values and rejects every other value before spawn.

Codex invocations explicitly select the Windows elevated sandbox while ignoring operator configuration. This selects a sandbox backend; commands still receive only the capability's read-only or workspace-write scope, with approvals disabled and network access denied. This retained policy does not make Windows service runners supported. A missing backend remains a failure, and Copilot does not run a sandbox setup command or select full access as recovery. Consult the official Windows sandbox guide for administrator provisioning and managed restrictions.

The native shell hash fixtures explicitly load the system Utility and Management manifests, because the hash script depends on Management commands. They retain private profiles, disabled module discovery and their bounded startup deadline. A missing command in those fixtures is separate from a real Codex sandbox setup failure; neither a probe job nor a fixture proves successful agent editing.

A Codex process can exit successfully after a shell tool failed. If bounded provider stderr reports the known sandbox setup mutex error, the run logs reported-sandbox-setup-mutex and directs you to inspect runner setup, even when the CLI exits 0. This is a provider-reported hint; a completed process does not certify that repository reads or edits ran. Historical reproductions used the same runner identity, executable and managed policy. Windows service Codex execution is now unsupported; route new Codex jobs to macOS or Ubuntu. Copilot does not expose raw stderr or change the sandbox backend in response.