Environment variables

Untether supports a small set of environment variables for logging and runtime behaviour.

Logging#

CLI behaviour#

Config overrides#

Any key on Untether’s settings models can be set from the environment as UNTETHER__<SECTION>__<KEY> (prefix UNTETHER__, nested sections joined with __, case-insensitive). An env value wins over the same key in untether.toml; other keys in that section still come from the file.

UNTETHER__WATCHDOG__LIVE_SESSIONS=false
UNTETHER__TRANSPORTS__TELEGRAM__FOLLOWUP_MODE=steer
UNTETHER__PROGRESS__VERBOSITY=verbose

This covers the top-level keys and the [transports.telegram], [projects.*], [plugins], [footer], [preamble], [progress], [watchdog], [cost_budget], [auto_continue], [loop] and [security] sections. It does not reach the engine tables ([claude] / [engines.claude], …) or [triggers], which are read from the TOML file only. The settings cache re-parses when any UNTETHER__* value changes (#506), but the service only sees its own environment, so set these in the unit (or a drop-in) and restart.

Keep secrets in the config file

Variables starting with UNTETHER_ are on the environment allowlist that Claude Code and Pi subprocesses inherit, so an UNTETHER__* override (a bot token or voice API key included) is visible to those engines. Put secrets in untether.toml (mode 600) rather than in UNTETHER__* variables.

Voice transcription#

Engine-specific#

Runner environment#

These variables are set (or removed) automatically by Untether in the engine subprocess environment.

Not a security concern

UNTETHER_SESSION is a simple signal variable, not a credential or secret. It tells Claude Code plugins that the session is running via Telegram so they can avoid interfering with Untether’s single-message output model. Plugins like PitchDocs check for this variable and skip blocking hooks that would otherwise consume the final response with meta-commentary instead of the user’s requested content. See the PitchDocs interference audit for the full analysis.

Env allowlist (Claude/Pi)#

As of v0.35.2, arbitrary process env vars are not forwarded to Claude/Pi subprocesses (#198). Only the built-in allowlist in src/untether/utils/env_policy.py (plus your [security] extras) is passed through:

• Exact names: OS essentials (PATH, HOME, USER, LOGNAME, SHELL, TERM, LANG, LC_ALL, LC_CTYPE, TMPDIR, TMP, TEMP, TZ); CLI output (NO_COLOR, CI, FORCE_COLOR, COLORTERM, CLICOLOR, CLICOLOR_FORCE); XDG_RUNTIME_DIR, XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME, XDG_STATE_HOME; language runtimes (PYTHONPATH, PYTHONUNBUFFERED, PYTHONDONTWRITEBYTECODE, PYTHONIOENCODING, NODE_PATH, NODE_OPTIONS, LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, DYLD_FALLBACK_LIBRARY_PATH); git/SSH (SSH_AUTH_SOCK, SSH_AGENT_PID, GIT_CONFIG_GLOBAL, GIT_SSH_COMMAND); provider keys (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID, OPENAI_PROJECT_ID, GOOGLE_API_KEY, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, GOOGLE_APPLICATION_CREDENTIALS, GEMINI_API_KEY, XAI_API_KEY, GROQ_API_KEY, CEREBRAS_API_KEY, DEEPSEEK_API_KEY, MISTRAL_API_KEY, FIREWORKS_API_KEY); GITHUB_TOKEN, GITHUB_PERSONAL_ACCESS_TOKEN, GH_TOKEN; CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID; BWS_ACCESS_TOKEN (a default since v0.35.3); UNTETHER_SESSION; PROJECT_ROOT, DIRENV_DIR.
• Prefixes: CLAUDE_, CLAUDE_CODE_, MCP_, MAX_MCP_, LC_, UV_, NPM_, PNPM_, NODE_, PIP_, UNTETHER_.

The Claude runner always execs under env -i KEY=VAL …, so the resolved environment is exactly the allowlist (#361). When [security] env_audit = true (default — see config reference), Untether also samples /proc/<pid>/environ once at session start and logs claude.env_audit.leaked_var for any non-allowlisted name it finds.

Extending the allowlist (v0.35.3+)#

If a plugin or MCP server depends on a specific variable, add it to the allowlist via TOML config — no fork, no re-install (#409):

[security]
env_extra_allow = ["OP_SERVICE_ACCOUNT_TOKEN", "DOPPLER_TOKEN"]   # exact names
env_extra_prefix_allow = ["VAULT_", "INFISICAL_"]                  # families

Names must match [A-Z_][A-Z0-9_]*. Untether emits one env_policy.user_extension INFO log per process at first runner spawn so the addition is visible in journalctl. The runtime audit also honours these so user-allowed names aren’t false-flagged as leaks. See security guide for the full discussion.

If you’d rather the new variable ship as a default for every Untether user, open a PR adding it to _EXACT_ALLOW / _PREFIX_ALLOW in src/untether/utils/env_policy.py. Setting [security] env_audit = false turns off the runtime audit only; the allowlist and the env -i wrap stay on.

Env for Codex and OpenCode#

Untether does not filter the Codex or OpenCode environment: both CLIs are spawned with Untether’s full process environment (so are the deprecated, unsupported Gemini CLI and AMP engines). [security] env_extra_allow has no effect on them (there is no allowlist to extend). Per-runner filtering for these engines is tracked in #375.

What an MCP server sees is decided by the engine, not by Untether, and the two engines differ:

[mcp_servers.trello]
command = "/home/me/bin/trello-mcp.sh"
env_vars = ["BWS_ACCESS_TOKEN"]   # forward by name; don't paste the secret into `env`

{
  "mcp": {
    "trello": {
      "type": "local",
      "command": ["/home/me/bin/trello-mcp.sh"]
    }
  }
}

Untether’s environment is not your shell’s

The variable has to be in Untether’s process environment, not just your interactive shell. Under systemd that means the unit’s EnvironmentFile= — contrib/untether.service reads %h/.untether/.env — not ~/.bashrc or a direnv .envrc. After adding a variable there, restart the service. OpenCode’s "environment": {"X": "{env:X}"} substitutes an empty string when X is unset, so the variable arrives set-but-empty rather than missing.

See the Codex MCP docs and OpenCode MCP servers for the full config schema.

MCP wrapper scripts under set -u#

A wrapper script that runs set -u (or set -eu) exits with VAR: unbound variable the moment it references a variable that isn’t set. The MCP server never starts, and the engine reports it as failed at session start; in Telegram you just see a run without those tools. Guard every variable reference:

Use the colon forms: they treat an empty value like an unset one, which matters for OpenCode’s {env:VAR} substitution (see above).

#!/usr/bin/env bash
set -euo pipefail
: "${BWS_ACCESS_TOKEN:?BWS_ACCESS_TOKEN is not set in the engine environment}"
: "${TRELLO_SECRET_ID:=00000000-0000-0000-0000-000000000000}"   # := assigns a default
TRELLO_TOKEN="$(bws secret get "$TRELLO_SECRET_ID" | jq -r .value)"
export TRELLO_TOKEN
exec trello-mcp-server

(Every variable the script touches is guarded. export X="$(…)" on one line would hide a failing bws call from set -e, so the assignment and the export are kept separate.)

if [ -n "${BWS_ACCESS_TOKEN:-}" ]; then
  exec my-mcp-server --token-from-bws
else
  exec my-mcp-server --read-only
fi

The :? message goes to the MCP server’s stderr, which the engine writes to its own log (OpenCode: mcp stderr: …; Codex: MCP server stderr (<program>): …), not to Telegram. Check there when a server’s tools are missing.