The framework is env-driven so a fresh user can clone + run without editing source. Every variable listed here is honoured by agent_runner.py, install.sh, deploy.sh, or the rendered launchd plists.
For the operator-config template, see .alfredrc.example.
| Var | Used by | Default | Notes |
|---|
GH_ORG | agent_runner._full_repo (every gh helper) | (none: raises) | Bare repo slugs (backend) get resolved to <GH_ORG>/<slug>. |
| Var | Used by | Default | Notes |
|---|
OPERATOR_NAME | agent prompts | (blank → “the operator”) | Substituted via load_prompt(..., extra_vars=...). |
OPERATOR_EMAIL | agent prompts | (blank) | Same. |
OPERATOR_GH_HANDLE | some prompts | (blank) | Used when distinct from GH_ORG. |
HERMES_HOME is the alfred-os runtime root. The name is historical; it does
not mean hermes-agent is installed or required.
| Var | Used by | Default |
|---|
HERMES_HOME | everything | $HOME/.hermes |
WORKSPACE_ROOT | agent_runner.WORKSPACE = WORKSPACE_ROOT/product | $HOME/code |
CLAUDE_BIN | agent_runner.claude_invoke | claude (PATH) |
CLAUDE_CONFIG_DIR | claude auth profile selection | (Claude default) |
CODEX_BIN | agent_runner.codex_invoke | codex (PATH) |
CODEX_MODEL | optional model override for codex exec | (Codex default) |
CODEX_SANDBOX | codex exec --sandbox | read-only |
CODEX_APPROVAL_POLICY | codex exec -c approval_policy=... | never |
| Var | Used by | Default |
|---|
ALFRED_<CODENAME>_ENGINE | per-agent engine choice | runner default |
ALFRED_ENGINE | fleet-wide engine override | (none) |
ALFRED_REVIEW_ENGINE | legacy review-agent override | (none) |
ALFRED_<CODENAME>_MAX_TURNS | optional per-agent Claude turn cap | runner default |
ALFRED_<CODENAME>_CODEX_SANDBOX | per-agent Codex sandbox | CODEX_SANDBOX |
ALFRED_<CODENAME>_CODEX_WRITE | shortcut for workspace-write | 0 |
bin/alfred engine status/set persists per-agent engine choices under $HERMES_HOME/state/engines/<codename>.
| Var | Used by | Default |
|---|
ALFRED_SHIPPED_SUMMARY_REPOS | alfred shipped / alfred-shipped-summary.py watched repo list | (none) |
ALFRED_SHIPPED_SUMMARY_QUERY_LIMIT | per-window GitHub query limit | 1000 |
| Var | Used by | Default |
|---|
ALFRED_DISABLE_CLAUDE_AUTH_REPAIR | disables automatic Claude auth refresh attempts | 0 |
CLAUDE_CONFIG_DIR | bin/hermes-claude and launchd env | (primary Claude profile) |
| Var | Used by | Default |
|---|
SLACK_WEBHOOK_URL | slack_post (env-var path, highest priority) | (none) |
SLACK_WEBHOOK_SECRET_ID | slack_post (AWS path) | alfred/slack-webhook |
SLACK_WEBHOOK_SECRET_REGION | slack_post (AWS path) | us-east-1 |
SLACK_BOT_TOKEN | Block Kit / thread helpers | (none) |
SLACK_BOT_TOKEN_SECRET_ID | bot token AWS path | alfred/slack-bot-token |
SLACK_BOT_TOKEN_SECRET_REGION | bot token AWS region | us-east-1 |
SLACK_HOME_CHANNEL | default bot channel | alfred |
BATMAN_APPROVAL_CHANNEL | legacy alias for SLACK_HOME_CHANNEL | (none) |
Resolution order: env -> 30-day disk cache at $HERMES_HOME/state/slack-webhook.cache -> AWS Secrets Manager. First hit wins.
| Var | Used by | Default |
|---|
ALFRED_HUNTRESS_AWS_PROFILE, ALFRED_GORDON_AWS_PROFILE | role runners that touch AWS | (none: AWS checks disabled or use default chain) |
AWS_PROFILE | set by role runners around owned aws ... calls | (none) |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_SECURITY_TOKEN | stripped before aws ... calls in agents that need pure-profile auth | (operator’s SSO leakage) |
| Var | Used by | Default |
|---|
HERMES_DOCTOR | every agent’s doctor_mode() check | 0 |
Set to 1 and any agent runner will emit [<NAME>-DOCTOR-OK] and exit 0 without side effects.
| Var | Used by | Default |
|---|
ALFRED_SPEND_RETENTION_DAYS | agent-cleanup.py (in consumer fleets) | 90 |
ALFRED_TRANSCRIPT_RETENTION_DAYS | same | 30 |
ALFRED_EVENTS_RETENTION_DAYS | same | 30 |
ALFRED_CLAIM_MAX_AGE_HOURS | stale-claim sweep | 4 |
| Var | Used by | Default |
|---|
ALFRED_NONINTERACTIVE | install.sh (use defaults for every prompt) | (interactive) |
ALFRED_SKIP_NPM | skip Claude Code install | (run) |
ALFRED_SKIP_BREW | skip brew install | (run) |
ALFRED_FORCE_LINUX | override the macOS check | (refuse) |
| Var | Used by | Default |
|---|
LABEL_STATE_SWEEP_REPOS | examples/bin/label_state.py sweep-claims (default repo set) | (must pass --repo) |
LABEL_STATE_BIN | pre-push hook | (resolves via PATH then $HERMES_HOME/bin/) |
LABEL_STATE_SKIP_DEDUP_CHECK | pre-push hook | (enforce) |
| Var | Used by | Default |
|---|
ALFRED_OS_PUBLISH_PAGES | .github/workflows/site.yml deploy gate | (unset: build only) |
ALFRED_OS_SITE_URL | site/astro.config.mjs | https://alfred.luminik.io |
ALFRED_OS_SITE_BASE | same | / |
Override these to deploy under a custom domain (e.g. ALFRED_OS_SITE_URL=https://alfred-os.dev + ALFRED_OS_SITE_BASE=/).
The path-resolution block at the top of lib/agent_runner.py is the canonical contract. Every other config file (install.sh, _template.plist, agents.conf) renders into the same env-var shape.