Agent Overview

The agent command group runs autonomous compliance tasks using a selectable Codex or OpenCode harness. Codex is the default and retains Pretorin’s hosted model-proxy defaults. OpenCode can use any provider it supports. Both harnesses share Pretorin’s runtime selection, prompt, result, MCP, and model-coordinate patterns.

If you already use another AI agent (Claude Code, Cursor, etc.), use the MCP mode instead (pretorin mcp-serve) and connect Pretorin tools to your existing agent.

Installation

The Codex SDK and legacy agent packages are an optional dependency group — a plain pretorin install does not include them. Install the extra before using the Codex or legacy execution path:

pip install 'pretorin[builtin-agent]'

This pulls in openai-codex-sdk (Codex runtime) plus openai-agents and openai (the --legacy runtime). pretorin agent doctor checks the selected harness executable, not those Python packages, so install the extra before a Codex run even if the executable check is healthy.

The standalone binary builds do not bundle the agent runtime — they are built without the extra, so pretorin agent run is only available from a Python-package install. Use MCP mode with your own agent, or install pretorin[builtin-agent] from PyPI.

Running a Compliance Task

# Free-form task
pretorin agent run "Assess AC-02 implementation gaps for my system"

# Use a predefined skill
pretorin agent run --skill gap-analysis "Analyze my system compliance gaps"

Select a harness

Save the default used by both pretorin agent and new Campaigns:

# Default when nothing has been configured
pretorin agent configure --agent codex

# Select OpenCode and save a provider/model for interactive and Campaign use
pretorin agent configure \
  --agent opencode \
  --model openai/gpt-5.6-terra \
  --reasoning-effort low

configure also accepts --runtime auto|system|managed, an optional --model-provider, --reasoning-effort low|medium|high, and an absolute --executable path. It saves only non-secret selection data; provider credentials stay in the provider’s normal environment or credential store. Use --clear-model, --clear-model-provider, --clear-reasoning-effort, or --clear-executable to remove those overrides.

An explicit --agent on a run wins over PRETORIN_AGENT_HARNESS, which wins over the saved default. If none is set, Pretorin selects Codex.

A first explicit pretorin agent install --agent codex|opencode or pretorin campaign install --agent codex|opencode saves that choice when no selection exists. Without the option, either interactive install prompts and saves the answer. Later installs of an alternate harness do not replace the default; use agent configure to change it.

Options

Before Codex or OpenCode starts a task with an active system/framework, Pretorin runs the ordinary preflight once against the selected working directory. The session receives a private read-only copy containing the verified resolver verdicts and active recipe pins. A child command cannot refresh or replace that snapshot; start a new task after changing source configuration. Tasks without an active scope continue without a scoped preflight artifact.

Codex hosted-model setup

Use this setup when you want pretorin agent run to call Pretorin-hosted model endpoints.

# 0. Install the agent runtime (optional dependency group)
pip install 'pretorin[builtin-agent]'

# 1. Login with your Pretorin API key
pretorin login

# 2. Optional: override the default model proxy endpoint
#    (default: https://platform.pretorin.com/api/v1/public/model)
pretorin config set model_api_base_url https://your-proxy.example.com/v1

# 3. Validate runtime
pretorin agent doctor --agent codex
pretorin agent install --agent codex

# 4. Run a task
pretorin agent run "Assess AC-02 implementation gaps for my system"

Model Resolution

For Codex, --model/-m overrides the per-harness model saved by agent configure; without either override, the existing Pretorin model configuration resolves in this order:

1. OPENAI_MODEL environment variable
2. openai_model config key (pretorin config set openai_model ...)
3. Your org’s AI settings, fetched from the platform and cached
4. gpt-4o

For OpenCode, --model/-m overrides the saved per-harness model, then OPENCODE_MODEL is considered. An interactive run may leave the model unset and use OpenCode’s own configured default. A Campaign deliberately does not: it requires a concrete OpenCode model so that the choice can be frozen and reported. Save one with agent configure --agent opencode --model provider/model, or pass --model to campaign start. The provider prefix in a fully qualified coordinate is authoritative for credential selection. OpenCode does not expose a native provider named pretorin; choose a provider coordinate supported by OpenCode and configure that provider’s credential.

Reasoning effort resolves from an explicit agent run --reasoning-effort, then the selected harness’s saved agent configure value. Pretorin normalizes this portable surface to low, medium, or high and translates it for Codex or OpenCode. OpenCode receives the corresponding native --variant; because variant support is model-specific, Pretorin validates the exact authenticated model metadata and rejects unsupported values before model execution. If neither is set, Pretorin leaves the option out so the selected provider/harness keeps its native default.

The authenticated OpenCode variant probe currently requires POSIX process-group isolation. On Windows, leave the OpenCode effort unset (so its native default remains in effect) or use Codex until equivalent Job Object ownership is implemented.

pretorin agent run \
  --agent opencode \
  --model openai/gpt-5.6-terra \
  --reasoning-effort low \
  "Assess AC-02 implementation gaps for my system"

The --legacy runtime resolves differently — it consults neither the openai_model config key nor your org’s AI settings. Its order is:

1. OPENAI_MODEL environment variable (overrides --model rather than deferring to it)
2. --model/-m
3. gpt-4o

Endpoint-bound model credentials

Codex does not apply one unqualified key fallback chain. It binds credentials to the selected endpoint before launching the runtime:

• When the model URL is the /model endpoint derived from a Pretorin platform URL, only the API key paired with that exact platform deployment is eligible. This may be the temporary PRETORIN_API_KEY plus PRETORIN_PLATFORM_API_BASE_URL pair, or the endpoint/key pair saved by pretorin login.
• For a custom model URL selected by --base-url, PRETORIN_MODEL_API_BASE_URL, or saved model_api_base_url configuration, or for a non-pretorin provider, OPENAI_API_KEY is tried before the saved openai_api_key.
• A direct model key is never sent to any known Pretorin platform origin, including URL aliases that do not exactly spell the derived model path. If no matching platform key exists for the exact model proxy, the run fails closed before spawning Codex.
• Overriding only PRETORIN_PLATFORM_API_BASE_URL does not rebind the saved key to the new deployment. Supply both environment variables when changing the platform session.

Model and platform URLs must be absolute HTTP(S) URLs with a valid hostname or IP address and without embedded user information, whitespace, query strings, fragments, invalid percent escapes, or invalid ports.

The deprecated --legacy runtime retains its older compatibility precedence: it prefers the platform key by default and flips to OPENAI_API_KEY first when --base-url or OPENAI_BASE_URL is set. Its endpoint resolves as --base-url → OPENAI_BASE_URL → model_api_base_url (then the legacy harness_base_url / codex_base_url / openai_base_url config keys) → the default platform proxy.

Custom Model Endpoints

The agent supports any OpenAI-spec LLM endpoint, including:

• Azure OpenAI
• vLLM
• LiteLLM
• Ollama

Configure via --base-url, PRETORIN_MODEL_API_BASE_URL, or the model_api_base_url config key. The deprecated --legacy path uses the same configured endpoint and sends requests through the Responses API.

How it works

The shared resolver uses the same policy for Codex and OpenCode. In the default auto mode it tries an explicitly configured executable, then a compatible executable on PATH, then the checksum-pinned Pretorin-managed binary. A system executable must meet the maintained minimum version and required CLI capabilities. system allows the configured/PATH sources only and never downloads; managed ignores them and uses the managed artifact only. agent install resolves only the selected harness.

Each interactive session gets unique, ephemeral harness configuration, injects the Pretorin MCP server, and uses the shared compliance prompt and result contract. Concurrent Codex runs cannot replace one another’s route. The harness-specific session adapter then streams bounded events and output.

Campaign workers reuse that same selected harness and runtime resolver, but use a stricter Campaign profile: one ephemeral configuration/home per attempt, a frozen least-privilege assignment, the assigned Pretorin MCP server only, an assignment-specific MCP tool allowlist, read-only workspace posture, no web or delegated-task tools, and only bounded observer-safe event records. OpenCode denies its native shell. Codex retains sandboxed commands for workspace inspection, but their environment excludes bearer and source credentials, their network is disabled, and Pretorin behaviorally proves the actual workspace is not writable before model launch. A workspace that contains owner credential/configuration paths, or whose host sandbox cannot enforce read-only access, is rejected.

Execution Posture

The interactive Codex session is deliberately unattended, because a compliance run has to inspect your repository and call platform tools without stopping for approval at each step:

• Permissions: the generated pretorin_interactive named profile grants native tools read/write access to the selected workspace and Pretorin scratch space, permits the minimum operating-system reads needed to run commands, denies native network access, and denies other owner files. Run it against a working tree you are willing to hand to an agent.
• Approvals: never — no interactive confirmation prompts. Shell commands and tool calls are echoed to the terminal as they run, so the stream is your audit trail.
• Working directory: --working-dir/-w, or the current directory when the flag is omitted. This is the root the agent explores for code evidence.
• Web search: disabled in the managed config.toml. Everything the agent asserts comes from your workspace, the Pretorin platform, or any MCP servers you configured yourself.

The named profile governs Codex native tools; Codex startup and MCP server processes are separate trust boundaries. Pretorin keeps model and platform keys out of model-generated shell environments, but the trusted Pretorin MCP child retains the platform access needed for compliance tools. Any additional MCP server you configure can broaden filesystem, network, or external-service access according to that server’s own behavior. Codex passes only explicitly configured MCP environment names. OpenCode starts both its built-in and extra local MCP servers through an environment-clearing launcher, so the built-in server receives only the platform pair plus the original user home needed for Pretorin context and recipes, while each extra server receives only its declared environment in addition to ordinary isolated runtime variables.

Interactive OpenCode runs deny shell, file-edit, write, web, and delegated-task tools in their isolated session configuration. Campaigns apply the stricter least-privilege worker profile regardless of which supported harness is selected. A harness is an agent execution mechanism, not a security sandbox; run only binaries you trust.

The --legacy runtime has no sandbox of its own — it only calls platform function tools plus whatever MCP servers you configured, and never runs shell commands.

See Agent Runtime Management for the full set of pretorin agent lifecycle commands.