Environment Variables

Environment variables override stored configuration values.

Authentication & API

Context

Agent Runtime

Environment isolation for pretorin agent run

The Codex subprocess does not inherit your full shell environment. Pretorin builds a bounded environment with its isolated CODEX_HOME, the resolved model key and URL, PATH, HOME, and the separately resolved endpoint-bound Pretorin platform key/URL pair.

Those credentials then have separate destinations:

• Codex itself receives the model pair. The configured Pretorin MCP child receives only the authorized PRETORIN_API_KEY and PRETORIN_PLATFORM_API_BASE_URL pair by variable name; it never receives OPENAI_API_KEY.
• Model-generated shell commands use a safe name allowlist containing ordinary runtime variables such as HOME, PATH, locale, temporary-directory, and certificate paths. Neither model nor platform bearer keys reach shell tools.
• Codex native tools run under the generated pretorin_interactive profile: the selected workspace is readable/writable, native networking is disabled, and owner files outside that workspace are not part of the native tool surface. Minimal operating-system runtime paths and scratch remain available.
• PRETORIN_SYSTEM_ID, PRETORIN_FRAMEWORK_ID, and unrelated exported secrets are not forwarded. The MCP server can still read saved context through the passed-through HOME.
• Environment-only CI authentication is supported. When targeting a deployment other than the saved one, export both PRETORIN_API_KEY and PRETORIN_PLATFORM_API_BASE_URL; a URL-only override fails closed instead of combining the new URL with a saved key.
• HOME is passed through, so ~/.pretorin/config.json, the recipe folders, and ~/.pretorin/mcp.json all resolve normally.
• Extra MCP servers that need their own secrets (for example GITHUB_TOKEN) must declare them in the env block of their owner-only ~/.pretorin/mcp.json entry; exporting them in your shell is not enough. Never put secrets in the shareable project .pretorin-mcp.json. See Agent Runtime.

The native Codex permission profile does not sandbox Codex startup or MCP server processes. The trusted Pretorin MCP child uses the passed-through home and endpoint-bound platform pair to load the user’s compliance configuration. Additional MCP servers run with their own authority and can broaden access; configure only servers you trust.

OpenCode also receives an isolated home/XDG configuration, an endpoint-bound Pretorin platform pair, and a model-provider credential allowlist. Interactive OpenCode denies shell, file-edit, write, web, and delegated-task tools. Its built-in Pretorin MCP is launched through an environment-clearing helper with only the endpoint-bound platform pair and the original user home needed to read saved Pretorin context and user recipes. A configured non-Pretorin local MCP uses the same helper and receives only ordinary isolated runtime variables plus the exact env names declared for that server, never OpenCode’s model, platform, or OAuth credentials implicitly. Campaign children apply the stricter Campaign worker profile for either harness. Every other pretorin command runs in your shell and honors the variables below normally.

Source Attestation

Behavior

Campaign Runner

These variables apply to local Plan-backed Campaign execution. Native components are installed and verified with pretorin campaign install; the standard package and standalone distribution include the supported Python dependencies. The former campaign-runner extra is a compatibility-only alias.

There is no global reasoning-effort environment override. Save a per-harness low, medium, or high value with pretorin agent configure --reasoning-effort, or pass the same option to agent run or campaign start. If unset, the provider/harness default is retained.

Pretorin sets PRETORIN_PLANS_DIR, PRETORIN_CAMPAIGNS_DIR, and PRETORIN_PREFLIGHT_DIR internally for the assigned MCP child. It also sets PRETORIN_PREFLIGHT_READ_ONLY=1 for prepared work. The first two identify the canonical local stores selected by the supervisor. The third points at a session-local copy of the one pre-work artifact containing only the assigned system/framework’s verified bindings and exact recipe activation pins. The read-only flag prevents MCP tools and direct CLI commands in that child from refreshing or replacing it. These are runtime plumbing, not operator configuration; do not set them manually.

Normal local state lives under ~/.pretorin/: Plans in plans/, Campaign records in campaigns/, canonical preflight state in preflight/, managed Codex in bin/, managed OpenCode in runtimes/opencode/, and managed Hatchet in runtimes/hatchet/. Embedded Hatchet’s per-Campaign database defaults to campaigns/.hatchet/<campaign-plan-id>/. Detached supervisors discard raw stdout and stderr, while Codex/OpenCode attempt directories under runtimes/<harness>/attempts/ are removed when each attempt exits. These paths contain operational state and bounded receipts, not canonical platform artifact bodies.

PRETORIN_MCP_PROFILE=campaign-worker is set internally for an agent item’s MCP child process. It is a least-privilege tool-surface profile, not an operator configuration or a process sandbox.

Pretorin also sets the internal assignment and per-attempt harness home/config variables. Do not set them yourself. They are named here so you can recognize them when inspecting a child process, not so you can configure them:

• PRETORIN_CAMPAIGN_ASSIGNMENT carries the serialized item assignment to the harness process and its MCP child.
• PRETORIN_MCP_SOURCE_ENV_KEYS names, by variable name only, which evidence-source variables the MCP child is authorized to keep; anything not listed is dropped at that boundary.
• CODEX_HOME (Codex) and OPENCODE_CONFIG_CONTENT plus XDG_CONFIG_HOME/XDG_DATA_HOME/XDG_CACHE_HOME (OpenCode) point each attempt at its own ephemeral configuration tree instead of your real ~/.codex or ~/.config/opencode.

Each attempt receives a distinct ephemeral configuration tree and only an explicit environment allowlist. When OpenCode OAuth is configured, Pretorin uses OpenCode’s environment-only OPENCODE_AUTH_CONTENT mechanism; it never copies the token file into the attempt directory or serializes credentials into config, Plans, Campaign state, or observer events.

Campaign evidence-source credentials

Model-provider credentials, the Pretorin platform API key, and evidence-source credentials are separate trust domains. A Campaign resolves source values fresh for each exact system/framework attempt. Its trusted harness process temporarily carries the allowlisted values so the assigned Pretorin MCP child can inherit them; the worker tool profile has no shell or general environment-inspection surface. The MCP child retains source variables only when the authoritative preflight artifact authorizes that source. Values are never frozen into an assignment or persisted in harness configuration, Plans, Campaign records, or observer events.

For AWS, the current source allowlist is:

• direct/session credentials: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN;
• profiles and regions: AWS_PROFILE, AWS_DEFAULT_PROFILE, AWS_REGION, and AWS_DEFAULT_REGION;
• role/web identity: AWS_ROLE_ARN, AWS_ROLE_SESSION_NAME, and AWS_WEB_IDENTITY_TOKEN_FILE; and
• credential files: AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE.

AWS values are admitted only for a legacy aws_account preflight source or a normalized cloud_control_plane resolver whose provider is AWS. If the two explicit file variables are absent but the invoking HOME contains ~/.aws/config or ~/.aws/credentials, Pretorin converts the existing files to explicit absolute paths before replacing HOME with the attempt’s isolated directory. An AWS credential used by a model provider remains independently subject to the model-provider allowlist; source authorization does not broaden model access, or vice versa.

Campaign execution uses embedded Hatchet v0.105.16 with Hatchet SDK 1.39.0. Remote and multi-host execution are intentionally unsupported until Plans have a shared persistence contract. The embedded engine and Campaign state live under Pretorin-owned local state and can resume on the same host.

Self-Update

pretorin update runs its installer and verification steps in a subprocess whose environment is derived from your shell, with these adjustments. Except for PRETORIN_UPDATE_BASE_URL, you do not set any of these yourself — the rest document what the command does to the environment it passes down.

If neither installer layout is detected, the subprocess inherits your environment unchanged apart from the PYTHONPATH / PYTHONHOME removal.

Cloud Scanner Recipes

These are standard cloud-provider SDK environment variables. Pretorin’s bundled asset-inventory and cloud-baseline recipes honor them when scanning AWS/Azure.

Recipe Authoring

Precedence

For the platform API credential:

1. A nonblank PRETORIN_API_KEY is paired with the effective platform URL.
2. Otherwise, api_key in ~/.pretorin/config.json remains paired with its saved platform URL.

If an environment platform URL differs from the saved URL but no environment key is supplied, Pretorin does not reuse the saved key for that deployment.

For the platform API URL:

1. PRETORIN_PLATFORM_API_BASE_URL environment variable (highest)
2. PRETORIN_API_BASE_URL environment variable (legacy alias)
3. platform_api_base_url in ~/.pretorin/config.json
4. api_base_url in ~/.pretorin/config.json (legacy)
5. https://platform.pretorin.com/api/v1/public default

For the model API URL used by Codex:

1. PRETORIN_MODEL_API_BASE_URL environment variable (highest)
2. model_api_base_url in ~/.pretorin/config.json
3. The saved legacy harness_base_url or codex_base_url, in that order
4. The /model endpoint derived from the effective platform API URL above

For the Codex model key, eligibility is endpoint-bound rather than global:

1. A platform key paired with the platform URL whose derived /model endpoint exactly matches the selected model URL.
2. For a custom model URL selected by --base-url, PRETORIN_MODEL_API_BASE_URL, or saved model_api_base_url configuration, or a non-pretorin provider, OPENAI_API_KEY, then saved openai_api_key.

A direct model key is rejected for every URL on a known Pretorin platform origin, and a platform key is never sent to an unrelated model URL.

For the model name:

1. OPENAI_MODEL environment variable (highest)
2. openai_model in ~/.pretorin/config.json
3. Org AI settings from the platform (cached)
4. gpt-4o default

OpenCode uses its own provider configuration rather than Pretorin’s Codex model route. Select a concrete OpenCode-native provider/model for Campaigns. The isolated OpenCode configuration does not define a provider named pretorin, so that coordinate fails with configuration guidance instead of being mistaken for a platform-key-backed model.

For the source manifest:

1. PRETORIN_SOURCE_MANIFEST environment variable (highest) — JSON string or file path
2. .pretorin/source-manifest.json in the git repo root
3. ~/.pretorin/source-manifest-{system_id}.json
4. source_manifest key in ~/.pretorin/config.json

CI/CD Example

export PRETORIN_API_KEY=pretorin_your_key_here
export PRETORIN_DISABLE_UPDATE_CHECK=1
export PRETORIN_SYSTEM_ID=your_system_id

pretorin frameworks list
pretorin evidence push

These variables cover the CLI and pretorin mcp-serve. They do not carry into pretorin agent run, which runs its subprocess in an isolated environment — see Environment isolation for pretorin agent run.