Agent Overview

The agent command group runs autonomous compliance tasks using the Codex agent runtime. This is the Pretorin-hosted model mode — Pretorin manages the AI runtime and routes model calls through its /v1 endpoints.

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 agent runtime is an optional dependency group — a plain pretorin install does not include it, and pretorin agent run exits with “Codex agent features are not installed.” until you add it (the --legacy path checks a different package and reports “Agent features are not installed.”):

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 pinned Codex binary, not the Python packages, so it can report a healthy runtime while agent run still fails on a missing dependency — install the extra first.

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"

Options

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
pretorin agent install

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

Model Resolution

--model/-m is only the first step. With the flag unset, the model 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

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

Model Key Precedence

The Codex agent resolves API keys in this order:

1. config.api_key (from pretorin login) — used as bearer key for the platform model proxy
2. OPENAI_API_KEY environment variable
3. config.openai_api_key

When --base-url is explicitly provided (non-platform endpoint), the order changes to prefer OPENAI_API_KEY first, then falls back to config keys.

The --legacy runtime applies the same precedence, and additionally flips to the OPENAI_API_KEY-first order when OPENAI_BASE_URL is set in the environment — not just when --base-url is passed. 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 flag 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 agent runtime uses the Codex SDK with a pinned binary in ~/.pretorin/bin/ and an isolated CODEX_HOME at ~/.pretorin/codex/. The agent:

1. Downloads and pins a specific Codex binary version
2. Runs in an isolated CODEX_HOME environment (never touches ~/.codex/)
3. Automatically injects the Pretorin MCP server for compliance tool access
4. Streams events and output in real-time (unless --no-stream is passed)

Execution Posture

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

• Sandbox: danger-full-access — the session can read and write anywhere the invoking user can, and can run shell commands. Run it against a working tree you’re 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 --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.