Sortie does not use a .env file or a dedicated environment configuration block. Environment variables flow in four distinct directions — each covered in its own section below.

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 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.

Future agent adapters (Copilot CLI, Gemini CLI, etc.) will require their own authentication variables. This table will expand as adapters are added.

$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.

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.

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 sh -c subprocesses with a restricted environment. 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.

Inherited variables¶

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

POSIX allowlist — A fixed set of standard infrastructure variables:

PATH, HOME, SHELL, TMPDIR, USER, LOGNAME, TERM, LANG, LC_ALL, SSH_AUTH_SOCK

SORTIE_* prefix — All parent environment variables whose names start with SORTIE_ are inherited. 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.

Install script variables¶

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

Example:

SORTIE_VERSION=0.8.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 and exit codes
• Prometheus metrics reference — sortie_* metric names (these are Prometheus metrics, not environment variables)