Environment Variables

Sortie supports SORTIE_* environment variable overrides for most configuration fields, with optional .env file loading. Environment variables flow in six distinct directions - each covered in its own section below.

Configuration overrides

Twenty-four SORTIE_* environment variables override individual WORKFLOW.md configuration fields. Set them in the parent shell, in a .env file, or both.

Precedence

Four sources feed configuration, highest priority first:

1. SORTIE_* environment variables in the real process environment
2. .env file values (opt-in via SORTIE_ENV_FILE or --env-file)
3. WORKFLOW.md front matter YAML
4. Built-in defaults

A real env var always beats a .env value for the same key. Both beat whatever the YAML says.

Tracker variables

Polling variables

Workspace variables

Agent variables

Top-level variables

Control variables

These are not config field overrides. They control how overrides are loaded.

When --env-file is provided, the CLI resolves the path to absolute and exports it as SORTIE_ENV_FILE in the process environment. This ensures the value is captured by CollectSortieEnv and propagated to the MCP server, which runs in a different working directory and needs the absolute path to locate the .env file. When both SORTIE_ENV_FILE and --env-file are set, the CLI flag wins.

Type coercion

Fields not overridable via env

.env file support

Loading a .env file is opt-in.

Enable .env loading with either:

# Via environment variable
export SORTIE_ENV_FILE=/etc/sortie/prod.env
sortie WORKFLOW.md

# Via CLI flag (takes precedence over the env var)
sortie --env-file /etc/sortie/prod.env WORKFLOW.md

File format:

# /etc/sortie/jira.env
# Comments start with #. Blank lines are ignored.

SORTIE_TRACKER_KIND=jira
SORTIE_TRACKER_ENDPOINT=https://myco.atlassian.net
SORTIE_TRACKER_API_KEY="you@company.com:xpat_abc123def456"
SORTIE_TRACKER_PROJECT=PLATFORM
SORTIE_POLLING_INTERVAL_MS=30000
SORTIE_WORKSPACE_ROOT=~/workspace/sortie

GitHub adapter equivalent:

# /etc/sortie/github.env
SORTIE_TRACKER_KIND=github
SORTIE_TRACKER_API_KEY="ghp_your_personal_access_token"
SORTIE_TRACKER_PROJECT=myorg/myrepo
SORTIE_POLLING_INTERVAL_MS=30000
SORTIE_WORKSPACE_ROOT=~/workspace/sortie

Rules:

• One KEY=VALUE per line. No multiline values.
• # lines and blank lines are ignored.
• Optional single or double quotes around values - outer quotes are stripped, no escape processing.
• Only keys starting with SORTIE_ are loaded. All other keys are silently ignored.
• No variable interpolation within values. $HOME in a .env value is the literal string $HOME.
• Real environment variables always take precedence over .env values.
• The .env file is re-read on every WORKFLOW.md reload (file change detection). Real env vars require a process restart to change.

CSV encoding for list fields

active_states and terminal_states accept comma-separated values:

SORTIE_TRACKER_ACTIVE_STATES="To Do,In Progress"
SORTIE_TRACKER_TERMINAL_STATES="Done,Won't Do"

Each item is trimmed of surrounding whitespace. Empty items (from trailing commas or double commas) are discarded. An empty string produces an empty list.

Interaction with $VAR indirection

When a SORTIE_* override is set for a field, it replaces the YAML value entirely. The $VAR expansion that would normally run on the YAML value is skipped for that field. Values from env overrides are literal - $ characters are not expanded.

Example: WORKFLOW.md has api_key: $MY_TOKEN. If SORTIE_TRACKER_API_KEY=tok$5abc is set, the api_key becomes the literal string tok$5abc. The $MY_TOKEN indirection never executes. The $5 is not expanded.

Path fields (workspace.root, db_path) still receive ~ expansion even when set via env overrides. Only $VAR expansion is skipped.

Agent runtime variables

Agent adapters spawn subprocesses that inherit the full parent process environment. Sortie itself does not read or validate these variables - they pass straight through. If one is missing, the agent subprocess fails, not Sortie.

A missing ANTHROPIC_API_KEY is the most common claude-code deployment failure. Sortie starts and polls the tracker normally, but every agent session fails at launch with an auth error. The Sortie logs show a worker exit with exit_type=error; the root cause is only visible in the agent’s stderr output.

For copilot-cli, a missing GitHub token is the equivalent failure. The adapter’s preflight check validates that at least one of COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN is set, or that gh auth status succeeds. If none are available, StartSession fails with agent_not_found. The Copilot CLI itself implements try-and-fallback across these three variables - precedence matters only when multiple sources hold different valid tokens.

For codex, a missing CODEX_API_KEY produces the same pattern as Claude Code. Sortie starts normally, but every agent session fails with an authentication error during the app-server initialization handshake. If CODEX_API_KEY is unset, the adapter attempts to use cached credentials from ~/.codex/auth.json; if those are also absent or expired, StartSession fails with response_error. In SSH mode, the adapter injects CODEX_API_KEY into the remote command line because OpenSSH drops local environment variables by default.

For opencode, authentication is provider-specific and the adapter does not preflight it. OpenCode resolves credentials from its own environment, auth store, project .env, or opencode.json provider config, while the Sortie adapter injects or overrides a small managed OPENCODE_* set on every run and export subprocess.

In local mode, provider credentials come from the parent environment or from OpenCode’s own auth/config state, while the managed OPENCODE_* values above are injected by the adapter. In SSH mode, Sortie prefixes only the managed OPENCODE_* variables onto the remote command. Provider credentials such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, AWS_*, GITLAB_TOKEN, CLOUDFLARE_*, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT, and VERTEX_LOCATION must already exist on the remote host or in the remote host’s OpenCode auth/config state.

$VAR indirection in WORKFLOW.md

Selected WORKFLOW.md configuration fields resolve environment variable references at startup. This keeps secrets and deployment-specific values out of the workflow file.

When a field is overridden by a SORTIE_* environment variable, $VAR indirection is skipped for that field. See Configuration overrides.

Expansion modes

Two expansion functions exist. The mode depends on the field.

resolveEnvRef - Expands only when the entire trimmed value is a variable reference ($VAR or ${VAR}). Mixed content like https://example.com/$VAR is returned unchanged, preventing destructive rewriting of URIs and paths.

resolveEnv - Full os.ExpandEnv semantics. Expands $VAR and ${VAR} references anywhere in the string, including within larger values.

expandPath - Expands ~ or ~/ at the start of the value to the user’s home directory, then applies full os.ExpandEnv.

Fields with $VAR support

All other fields (including agent.kind, agent.max_turns, hook scripts, etc.) are treated as literal strings with no expansion.

The variable names in the table are user-defined conventions, not Sortie-internal identifiers. For the GitHub adapter, common conventions are $SORTIE_GITHUB_TOKEN or $GITHUB_TOKEN for tracker.api_key (a plain personal access token, not email:token format) and $SORTIE_GITHUB_PROJECT for tracker.project (an owner/repo string). See the GitHub adapter reference for per-field semantics.

Behavior when a variable is unset or empty

What this is not

$VAR indirection is not general shell expansion. It does not support:

• Command substitution ($(command) or `command`)
• Arithmetic expansion ($((1+2)))
• Default values (${VAR:-default})
• Glob expansion (*, ?)

Only the Go standard library os.ExpandEnv function is used. See the Go documentation for exact semantics.

Hook subprocess environment

Hook scripts (after_create, before_run, after_run, before_remove) run as subprocesses with a restricted environment. On POSIX systems, hooks execute via sh -c; on Windows, via cmd.exe /C. The full parent process environment is not inherited.

Injected variables

Sortie injects these variables into every hook invocation. They override any same-named variable from the parent environment.

after_run hook variables

These variables are injected only during after_run hook invocations.

See Configure self-review for usage examples.

Inherited variables

Beyond the injected variables above, hooks inherit two categories from the parent Sortie process:

Platform allowlist - A fixed set of standard infrastructure variables, varying by OS:

• POSIX (Linux, macOS): PATH, HOME, SHELL, TMPDIR, USER, LOGNAME, TERM, LANG, LC_ALL, SSH_AUTH_SOCK
• Windows: PATH, SYSTEMROOT, COMSPEC, PATHEXT, USERPROFILE, TEMP, TMP, APPDATA, LOCALAPPDATA, HOMEDRIVE, HOMEPATH, USERNAME

SORTIE_* prefix - All parent environment variables whose names start with SORTIE_ are inherited. This includes any SORTIE_* variables set via configuration overrides. This is the intended mechanism for passing additional values (API tokens, repository URLs, custom flags) into hooks without exposing the full process environment.

Stripped variables

Everything not in the allowlist and not prefixed with SORTIE_ is stripped. This includes:

• Cloud credentials: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, GOOGLE_APPLICATION_CREDENTIALS
• API tokens: JIRA_API_TOKEN, ANTHROPIC_API_KEY, GITHUB_TOKEN
• Application config: DATABASE_URL, REDIS_URL, etc.

This is a security boundary. Hooks run user-authored shell scripts; restricting their environment limits the blast radius of a compromised or buggy hook.

Providing additional values to hooks

Two approaches:

1. SORTIE_-prefixed variables. Export the value with a SORTIE_ prefix in the parent environment. It passes through automatically.

   export SORTIE_JIRA_API_TOKEN="xyztoken123"
   export SORTIE_REPO_URL="git@github.com:myorg/myrepo.git"
   sortie WORKFLOW.md

   Inside the hook:

   git clone "$SORTIE_REPO_URL" .

2. In-hook credential loading. Fetch credentials from external sources inside the script.

   source /etc/sortie/hooks-env
   aws sts get-caller-identity

Override precedence

When the same variable name exists in both the parent environment (via SORTIE_* passthrough) and the injected set, the injected value wins. For example, a parent SORTIE_ISSUE_ID=stale is overwritten by the orchestrator’s current SORTIE_ISSUE_ID for the active issue.

MCP server environment

The MCP tool server (sortie mcp-server) runs as a child process of the agent runtime, not of the Sortie orchestrator. The agent runtime constructs the MCP server’s environment exclusively from the env field in .sortie/mcp.json - variables not listed in that block do not reach the server. The worker writes per-session context variables and all SORTIE_*-prefixed process environment variables into this block before launching the agent.

Environment composition

The env block is built in two layers:

1. SORTIE_* process variables (lower precedence). The worker scans the orchestrator’s process environment and collects every variable whose name starts with SORTIE_. This captures credential variables (e.g., SORTIE_TRACKER_API_KEY), configuration overrides (e.g., SORTIE_POLLING_INTERVAL_MS), and any operator-defined SORTIE_* values.

2. Per-session variables (higher precedence). The worker writes these six variables, overriding any same-named key from layer 1:

Per-session variables always win. A stale SORTIE_ISSUE_ID in the process environment is overwritten by the orchestrator’s value for the active issue.

Credential delivery

Tier 2 tools (like tracker_api) need tracker API credentials. These reach the MCP server through the env block: the worker’s process environment contains credential variables (e.g., SORTIE_TRACKER_API_KEY), the SORTIE_* prefix scan collects them, and the worker writes them into .sortie/mcp.json. The MCP server’s config parser (applyEnvOverrides) resolves $VAR indirection in the workflow file against these variables.

When the operator uses --env-file, the CLI exports the resolved absolute path as SORTIE_ENV_FILE in the process environment. The prefix scan captures this variable, so the MCP server receives the .env file path and can load it through its own applyEnvOverrides mechanism.

The .sortie/mcp.json file is written with 0o600 permissions (owner read/write only) and resides within the per-issue workspace directory. The credential is already available to the agent subprocess via os.Environ() - writing it to the config file does not expand the agent’s access.

Controlled environment

Unlike the hook subprocess environment, which uses a POSIX allowlist plus SORTIE_* prefix filter on the parent process, the MCP server receives its environment entirely from the config file’s env block. Non-SORTIE_* variables from the orchestrator’s process (e.g., PATH, HOME, ANTHROPIC_API_KEY) are not passed to the MCP server. The SORTIE_* prefix acts as a bounded namespace - no non-Sortie secrets leak into the config file.

Relationship to hook variables

Four per-session variables (SORTIE_ISSUE_ID, SORTIE_ISSUE_IDENTIFIER, SORTIE_WORKSPACE, SORTIE_ATTEMPT) are shared with the hook subprocess environment. SORTIE_DB_PATH and SORTIE_SESSION_ID are specific to the MCP execution channel - hooks don’t receive them. In hooks, SORTIE_ATTEMPT is always present (defaulting to 0 on the first dispatch). In the MCP env block, SORTIE_ATTEMPT is written only when the orchestrator has attempt information (retries and continuations); on the very first dispatch it is absent from the per-session set, though it may still appear if the operator’s process environment contains a SORTIE_ATTEMPT variable captured by the SORTIE_* prefix scan.

Install script variables

The install.sh script accepts three environment variables that control installation behavior.

Example:

SORTIE_VERSION=1.9.0 SORTIE_INSTALL_DIR=/opt/bin \
  curl -sSL https://get.sortie-ai.com/install.sh | sh

See also

• WORKFLOW.md configuration reference - all configuration fields, defaults, and types
• CLI reference - command-line flags (including --env-file) and exit codes
• Agent extensions reference - tool schemas, MCP execution channel, and response formats
• Prometheus metrics reference - sortie_* metric names (these are Prometheus metrics, not environment variables)