Agent Runtime Management

Pretorin runs built-in agent work through the Codex binary. Interactive agent runs and newly prepared Campaigns share the saved runtime, model, provider, and reasoning settings.

Configure Codex

pretorin agent configure \
  --runtime auto \
  --model gpt-5.6-terra \
  --reasoning-effort low

Configuration options are:

Only non-secret settings are saved. API keys and OAuth tokens stay in their normal credential stores or environment variables. General platform and model endpoint settings remain under pretorin config.

An explicit --reasoning-effort on agent run or campaign start overrides the saved value for that run. Leave it unset, or clear it, to retain the Codex default.

Check runtime health

pretorin agent doctor

Doctor validates the Codex executable version and required CLI capabilities, reports resolved model/provider/reasoning coordinates, and checks model and endpoint-bound platform credential readiness. Malformed URLs or credentials missing for a concrete provider fail the check. Managed binaries also receive checksum and host execution-trust checks.

Resolve or install Codex

pretorin agent install

In auto mode, resolution is configured executable, compatible executable on PATH, then Pretorin-managed binary. system permits only the configured path or PATH and never downloads. managed ignores both and selects only the maintained Pretorin artifact.

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 by discovery.

Check version

pretorin agent version

This reports the Codex version, source, resolved path, model coordinates, reasoning effort, and readiness.

Manage MCP servers

Codex can connect to additional MCP servers beyond Pretorin. This lets it use other tools such as source-control or database readers during compliance work.

Configured servers are written into config.toml beneath the isolated CODEX_HOME for the run, and the selected --working-dir supplies project MCP configuration. The always-injected server name pretorin is reserved and receives only the endpoint-bound platform variable names.

Codex’s named filesystem and network permission profile applies to native Codex tools, not MCP server processes. Additional MCP servers can broaden filesystem, network, database, credential, and external-service access. Use only trusted servers and narrowly scoped credentials. Campaign attempts load only the external servers you explicitly configured, alongside 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>

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 removes the named server from both project and global files.

Configuration format

Both scopes use a top-level servers list:

Do not put secrets in .pretorin-mcp.json. The project file may be committed. Put literal per-server credentials only in the owner-only global ~/.pretorin/mcp.json file.

{
  "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; stdio requires command and http requires url. mcp-add has no --env option. When a stdio server needs a credential, add its literal env object by hand to the global file. Exporting an arbitrary secret in the parent shell does not add it to Codex’s exact environment. A project entry wins over a same-named global entry.

Invalid entries are skipped with a warning. Run pretorin agent mcp-list after hand-editing a file.

Runtime architecture

Each resolved Codex executable carries a stable source label and identity digest. Its source is an explicitly configured path, a compatible system installation, or a Pretorin-managed artifact.

• Managed binary location: ~/.pretorin/bin/
• Session configuration: every run gets a unique owner-only CODEX_HOME that is removed after the turn
• Compatibility: system binaries must satisfy the maintained version and CLI-capability contract
• Trust diagnostics: managed binaries are checksum-verified and checked for host launchability
• MCP injection: Pretorin MCP is automatically available

Interactive work with an active system and framework prepares the existing preflight artifact before model launch and injects an isolated read-only copy. This uses the same discovery, verification, and provisioning path as Campaign preparation.

Campaigns freeze the model/provider/reasoning effort, effective model endpoint, Codex version and exact source, managed status, and SHA-256 identity at preparation. Retry and resume require those coordinates and fail closed when the runtime is unavailable or changed. A later endpoint setting, PATH entry, or executable override cannot switch an existing Campaign.

The Campaign also freezes the preflight snapshot and identity, ordered item roster, child workflow, expected outputs, and process criteria. Every child and retry receives that snapshot and may read, but not verify or mutate, it. Resume validates the parent and child Plans against stored coordinates rather than deriving them from a newer package definition.

Campaign workers use the ordinary Codex workspace profile: project instructions are loaded, the workspace is writable, native shell and workspace tools remain available, and the source environment and configured MCP servers match an interactive run. Each attempt adds an ephemeral home, the frozen assignment, and an assignment-scoped Pretorin MCP server so platform writes remain attributable to the selected item.

Campaign source values are forwarded to Pretorin MCP by variable name, not serialized value. Native Codex and external-MCP reads remain available but do not receive Pretorin’s bounded source-read receipts; the assignment-bounded Pretorin readers do. Before Codex starts, the worker attests the finalized Pretorin tool catalog, every page of frozen source grants, snapshot identity, and required source-key forwarding. Operator-configured external MCP servers retain their separately declared authority and remain outside the CLI-owned approval boundary.