Agent Runtime Management

Pretorin’s shared agent runtime supports Codex and OpenCode. Codex is the default, but pretorin agent run and new Campaigns use the same saved harness selection and per-harness runtime settings.

Configure the shared harness

pretorin agent configure --agent codex

# Example OpenCode configuration suitable for Campaigns
pretorin agent configure \
  --agent opencode \
  --runtime auto \
  --model openai/gpt-5.6-terra \
  --reasoning-effort low

Configuration options are:

Only these non-secret settings are saved. API keys, OAuth tokens, and provider credentials stay in their normal credential stores or environment variables. Selection precedence is explicit --agent, PRETORIN_AGENT_HARNESS, saved default, then Codex.

With no environment or saved selection, a first pretorin agent install --agent codex|opencode or pretorin campaign install --agent codex|opencode saves that explicit choice. Either interactive install without --agent prompts for Codex or OpenCode and saves the answer. Once a default exists, installing the other harness only provisions it; use pretorin agent configure to change the shared selection. General platform and model-endpoint settings remain under pretorin config; harness selection and per-harness runtime settings belong under agent configure.

Reasoning effort uses the shared Pretorin values low, medium, and high. The saved value applies to both agent run and newly prepared Campaigns for that harness. An explicit --reasoning-effort on either command wins for that run. Leave it unset, or clear it, to retain the selected provider/harness default. Codex receives its native model_reasoning_effort setting. OpenCode receives its native --variant flag, so provider-specific lowering stays with OpenCode; a saved OpenCode effort therefore requires a concrete provider/model coordinate. Not every OpenCode model advertises all three portable variants. Pretorin checks the exact model metadata inside the final authenticated session and rejects an unsupported effort before launching the model instead of allowing OpenCode to silently use its default variant. That credential-bearing metadata probe currently requires POSIX process-group isolation; OpenCode reasoning-effort overrides fail closed on Windows until an equivalent Job Object ownership path is available. Leaving the effort unset continues to use OpenCode’s native default there.

Check Runtime Health

pretorin agent doctor --agent codex
pretorin agent doctor --agent opencode

Validates the selected executable’s version and required CLI capabilities, reports the resolved model/provider/reasoning effort coordinates, and checks both model-provider and endpoint-bound Pretorin platform credential readiness. Malformed model or platform URLs, or credentials missing for a concrete selected provider, fail the check. When both the interactive OpenCode model and provider are unset, missing direct provider credentials are reported as a warning because OpenCode may use its own configured default and native authentication. Managed binaries also receive checksum and host execution-trust checks. When an OpenCode reasoning effort is selected and credentials are available, doctor also verifies that the exact authenticated model advertises that native variant.

Resolve or install a harness

pretorin agent install --agent codex
pretorin agent install --agent opencode

In the default auto mode, resolution is configured executable → compatible executable on PATH → Pretorin-managed binary. system permits only the configured path or compatible PATH discovery and never downloads. managed ignores configured and PATH executables and selects only the maintained Pretorin artifact. install acts only on the selected harness.

Before a configured or PATH candidate is accepted, its version and capability probes run from a private temporary home and working directory with a minimal credential-free environment. Ambient platform, model-provider, and evidence-source secrets are not exposed merely by runtime discovery.

Check Version

pretorin agent version --agent codex
pretorin agent version --agent opencode

Shows the selected harness’s version, source, resolved path, model coordinates, reasoning effort, and readiness. Omit --agent on lifecycle commands to inspect the shared default.

Manage MCP Servers

The agent can connect to additional MCP servers beyond Pretorin. This lets the agent access other tools (filesystem, databases, etc.) during compliance tasks.

The supported execution paths read the same two MCP config files, but use them differently:

• Codex runtime (default): the servers are written into the isolated CODEX_HOME config.toml for that run and the selected --working-dir supplies project MCP configuration. The always-injected pretorin server receives only the endpoint-bound platform variable names. A configured server named pretorin is skipped, so that name is effectively reserved.
• OpenCode runtime: the servers are translated into the isolated OpenCode session configuration alongside the always-injected pretorin server. Every local server is started through an environment-clearing launcher: the built-in server receives the endpoint-bound Pretorin platform pair and original user home needed for saved context and recipes, while an extra server receives ordinary isolated runtime variables plus its own declared env names. Neither receives OpenCode model credentials implicitly. The interactive profile denies shell, file-write, web, and delegated-task tools.
• --legacy runtime: the servers are loaded as OpenAI Agents SDK server objects, and skipped entirely when --no-mcp is passed. This runtime does not reach Pretorin over MCP — the platform tools are in-process function tools — so nothing is injected and the pretorin name is not filtered. Naming a server pretorin there launches it as an ordinary extra server.

Codex’s named filesystem/network permission profile applies to native Codex tools, not to MCP server processes. Additional MCP servers can therefore broaden filesystem, network, database, or external-service access according to their own implementation. Configure only servers you trust and scope their credentials narrowly. Campaign attempts do not load these extra servers; they receive only Pretorin MCP with an assignment-specific enabled_tools list.

List Configured Servers

pretorin agent mcp-list

Add a Server

# stdio transport
pretorin agent mcp-add <name> stdio <command> --arg <arg1> --arg <arg2>

# http transport
pretorin agent mcp-add <name> http <url>

Options:

Examples:

pretorin agent mcp-add github stdio uvx --arg mcp-server-github
pretorin agent mcp-add aws http https://mcp.example.com/aws
pretorin agent mcp-add tools stdio node --arg /path/to/server --scope global

Remove a Server

pretorin agent mcp-remove <name>

mcp-remove takes no --scope — it removes the named server from both the project and global config files.

Config File Format

Both scopes use the same JSON shape — a top-level servers list, which is what mcp-add writes:

Do not put secrets in .pretorin-mcp.json. The project file is intended to be shareable and may be committed. Put literal per-server credential values only in the global ~/.pretorin/mcp.json. Pretorin writes its directory with owner-only permissions and the file as mode 0600; preserve those permissions when hand-editing it.

{
  "servers": [
    {
      "name": "github",
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-github"]
    },
    {
      "name": "aws",
      "transport": "http",
      "url": "https://mcp.example.com/aws"
    }
  ]
}

transport defaults to stdio when omitted; stdio requires command and http requires url. mcp-add has no --env flag. When a stdio server needs credentials, add its literal env object by hand to the owner-only global file, never the project file. This is also how an extra MCP server receives a secret during an interactive Codex run; exporting an arbitrary secret in the shell does not add it to Codex’s exact environment. A legacy name-keyed object ("servers": {"github": {...}}) is still parsed, but new entries are written in the list form. A project entry wins over a same-named global entry, so do not shadow a credential-bearing global server from the project file.

Entries that fail strict type or transport validation are skipped rather than failing the run, and Pretorin logs a warning identifying the invalid entry. Check pretorin agent mcp-list after hand-editing.

Runtime architecture

Each resolved executable carries a stable source label and an identity digest. The source is one of an explicitly configured path, a compatible system installation, or a Pretorin-managed artifact. Managed Codex and OpenCode artifacts live under Pretorin-owned state; session configuration is isolated from the user’s ordinary harness configuration.

• Managed binary locations: Codex uses ~/.pretorin/bin/; OpenCode uses ~/.pretorin/runtimes/opencode/<version>/<platform>/.
• Session configuration: every Codex run gets a unique owner-only CODEX_HOME child that is removed after the turn; OpenCode uses an equivalent ephemeral isolated home/XDG tree.
• Compatibility: system binaries are accepted only when they satisfy the maintained version and CLI-capability contract.
• Trust diagnostics: managed binaries are checksum-verified and checked for host launchability before use.
• MCP injection: Pretorin MCP server is automatically available to the agent

Interactive work with an active system/framework prepares the existing preflight artifact once before model launch and injects an isolated read-only copy into either harness. This uses the same discovery, verification, and provisioning entry point as Campaign preparation; it is not a second agent- or Campaign-specific preflight implementation.

Campaigns freeze the selected harness, model/provider/reasoning effort, effective model endpoint (the Codex route or the OpenAI/Anthropic OpenCode provider route), executable version, exact source, managed status, and SHA-256 identity digest at preparation time. Retry and resume require those same coordinates and fail closed when the exact runtime is unavailable or changed; a new model-endpoint setting, PATH entry, executable override, or shared harness selection cannot switch an existing Campaign. Legacy Campaign records that predate endpoint freezing retain their previous same-host fallback behavior. The Campaign record also freezes the prepared preflight artifact and its SHA-256 identity, ordered item roster, child workflow, expected outputs, and process criteria. Every child and retry receives that exact snapshot and may read, but not verify or mutate, it. Resume validates the parent and child Plans against those stored coordinates rather than re-deriving them from a newer package definition. Records created before the shared snapshot, worker contract, or ordered roster was persisted remain readable for status/cancellation but must be replaced by a new Campaign before agent execution.

Campaign workers reuse this harness and resolver but apply a stricter profile than an interactive run: one ephemeral home/configuration per attempt, the frozen least-privilege assignment, the assigned Pretorin MCP server only, a read-only workspace, and no web or delegated-task tools. OpenCode denies its native shell. Codex retains sandboxed inspection commands with a safe, non-secret shell-variable allowlist and native networking disabled. Before launching the model, Pretorin runs the selected Codex binary against the exact workspace and proves that workspace writes and outside owner-file reads are blocked while attempt scratch works. Roots that overlap known home credential/configuration paths, and paths whose host sandbox cannot enforce read-only access, fail closed. Only bounded observer-safe records leave the harness session. OpenCode configuration is serialized so its raw pre-parser cannot expand {env:...} or {file:...} text embedded in a frozen assignment; the exact literal value is restored only when JSON is decoded. Campaign source credentials are forwarded to the built-in MCP by authorized variable name, not serialized value.