Agent Overview

The agent command group runs autonomous compliance tasks through the Codex binary. Pretorin owns runtime resolution, session isolation, prompt and result contracts, MCP injection, and endpoint-bound model credentials.

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

Installation

The Codex SDK is in an optional dependency group. Install the extra before using pretorin agent run from a Python-package installation:

pip install 'pretorin[builtin-agent]'

Standalone Pretorin binaries do not bundle the Python Codex SDK. Use MCP mode with your own agent, or install pretorin[builtin-agent] from PyPI.

Run 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"

The supported options are:

Before Codex starts a task with an active system and framework, Pretorin runs the ordinary preflight 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.

Configure Codex

Use agent configure to save non-secret runtime and model settings shared by interactive runs and newly prepared Campaigns:

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

configure also accepts an optional --model-provider and an absolute --executable path. Use --clear-model, --clear-model-provider, --clear-reasoning-effort, or --clear-executable to remove an override. API keys and OAuth tokens remain in their normal credential stores or environment variables.

Hosted-model setup

Use this setup when pretorin agent run should call Pretorin-hosted model endpoints:

# 1. Install the Codex runtime dependency
pip install 'pretorin[builtin-agent]'

# 2. Login with your Pretorin API key
pretorin login

# 3. Optionally override the default model proxy endpoint
pretorin config set model_api_base_url https://your-proxy.example.com/v1

# 4. Validate and resolve Codex
pretorin agent doctor
pretorin agent install

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

Model resolution

--model/-m overrides the model saved by agent configure. Without either override, Pretorin resolves the model in this order:

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

Reasoning effort resolves from the command’s explicit --reasoning-effort, then the saved agent configure value. Pretorin accepts low, medium, or high and passes the value to Codex as model_reasoning_effort. If neither is set, Codex keeps its native default.

Endpoint-bound model credentials

Pretorin binds credentials to the selected model endpoint before launching Codex:

• 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 and 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 a known Pretorin platform origin. If no matching platform key exists for the exact model proxy, the run fails before spawning Codex.
• Overriding only PRETORIN_PLATFORM_API_BASE_URL does not rebind a saved key to a different 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 no embedded user information, whitespace, query string, fragment, invalid percent escape, or invalid port.

Custom model endpoints

Codex can use OpenAI-compatible endpoints such as Azure OpenAI, vLLM, LiteLLM, and Ollama. Configure one with --base-url, PRETORIN_MODEL_API_BASE_URL, or the model_api_base_url config key.

How it works

The Codex resolver supports three policies. In the default auto mode it tries an explicitly configured executable, then a compatible executable on PATH, then the checksum-pinned Pretorin-managed binary. system uses only the configured path or PATH and never downloads. managed ignores those sources and uses only the managed artifact. pretorin agent install resolves Codex under the configured policy.

Each interactive session gets a unique, ephemeral CODEX_HOME, the Pretorin MCP server, configured user MCP servers, the shared compliance prompt, and a bounded result contract. Concurrent runs cannot replace one another’s route.

Campaign workers are ordinary Codex workspace sessions. They load project instructions, retain native shell and workspace tools, receive writable workspace access and the same source environment, and load the same configured MCP servers as an interactive run. Pretorin adds an ephemeral CODEX_HOME, a frozen assignment, assignment-scoped Pretorin MCP tools, and observer-safe event records. Before model launch, the worker attests the finalized Pretorin MCP catalog, frozen source grants, snapshot identity, and required source-key forwarding.

Execution posture

Interactive Codex sessions are unattended so a compliance run can inspect the workspace and call platform tools without stopping for approval on each step:

• Permissions: the generated pretorin_interactive profile grants native tools read/write access to the selected workspace and Pretorin scratch space and permits source/network access needed for ordinary workspace work. Use a working tree and configured source credentials you are willing to hand to an agent.
• Approvals: never. Shell commands and tool calls are streamed as an audit trail.
• Working directory: --working-dir/-w, or the current directory when the option is omitted.
• Web search: disabled in the managed configuration. Assertions come from the workspace, Pretorin platform, or MCP servers you configured.

The Codex profile governs native tools, not MCP server processes. Additional MCP servers can broaden filesystem, network, database, or external-service access according to their own implementation. Configure only servers you trust and scope their credentials narrowly.

See Agent Runtime Management for lifecycle commands and MCP configuration.