Agent Runtime Management

The agent runtime uses a managed Codex binary with isolated configuration.

Check Runtime Health

pretorin agent doctor

Validates that the Codex runtime is properly installed and configured. On macOS, this also runs the system execution trust check for the pinned binary so revoked or blocked signatures are reported before an agent run.

Install Codex Binary

pretorin agent install

Downloads the pinned Codex binary to ~/.pretorin/bin/. The version is pinned by the CLI to ensure compatibility.

Check Version

pretorin agent version

Shows the pinned Codex version and whether it’s currently installed.

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.

Both runtimes read the same two config files, but they use them differently:

• Codex runtime (default): the servers are written into the isolated CODEX_HOME config.toml on each run, alongside the always-injected pretorin server. A configured server named pretorin is skipped, so that name is effectively reserved.
• --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.

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:

{
  "servers": [
    {
      "name": "github",
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    {
      "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, so add the per-server env object by hand when a stdio server needs credentials. A legacy name-keyed object ("servers": {"github": {...}}) is still parsed, but new entries are written in the list form.

Entries that fail to parse are skipped silently rather than failing the run, so check pretorin agent mcp-list after hand-editing.

Runtime Architecture

The Codex runtime is fully isolated:

• Binary location: ~/.pretorin/bin/
• Configuration: ~/.pretorin/codex/ (CODEX_HOME)
• Version pinning: The CLI pins a specific Codex version for compatibility
• Trust diagnostics: pretorin agent doctor checks whether the pinned binary is trusted by the host OS before it is launched
• MCP injection: Pretorin MCP server is automatically available to the agent

This isolation ensures the agent runtime never interferes with any user-installed Codex instances.