Configuration

Untether reads configuration from ~/.untether/untether.toml.

If you expect to edit config while Untether is running, set:

untether config

untether config set watch_config true

toml

watch_config = true

Top-level keys#

Any key on the settings models below (everything except the engine tables and [triggers]) can also be set from the environment as UNTETHER__<SECTION>__<KEY> (e.g. UNTETHER__WATCHDOG__LIVE_SESSIONS=false), which wins over the TOML value. See environment variables.

Hot-reload vs restart-required#

When watch_config = true, Untether watches untether.toml and applies most changes immediately. A handful of settings require a process restart because they’re bound to resources (network sockets, bot token, session-mode machinery) that can’t be swapped live.

Changes are detected by file content, not timestamps (#839): a save that doesn’t change anything (including touch) doesn’t reload, while two quick same-size edits are both applied. If a reload fails because of something outside the file (say, an engine CLI missing from PATH), fix it and touch the config to retry. A symlinked config is followed when the link is re-pointed; if the new target lives in a different directory, restart Untether so later in-place edits of that file are seen.

Editing a field marked 🔄 (restart-required) posts a warning to the project chats and admin DMs (”⟳ Setting chat_id changed — restart required to take effect.”, followed by a “To apply:” line naming the service that’s actually running, #927) and logs config.reload.transport_config_changed. Other Telegram transport changes apply without a message and log config.reload.transport_config_hot_reloaded.

Separately from the watcher, the per-run settings ([footer], [progress], [watchdog], [preamble], [cost_budget], [auto_continue], [security], …) are re-read on every use, even with watch_config = false, so an edit applies on the next run or the next turn of a live session (#269). Since 0.36.0 the file is only re-parsed when its contents (or the UNTETHER__* env vars) change, and each real parse logs one INFO config.loaded reason=first_load|content_changed|env_changed line (#506). Set UNTETHER_SETTINGS_CACHE=0 to turn the cache off (see environment variables).

The authoritative list for the Telegram transport lives on TelegramTransportSettings.RESTART_REQUIRED_FIELDS (see src/untether/settings.py) so code, docs, and UI can’t drift; the other rows below are enforced where each resource is created. Editing untether.toml to update one of these while the service runs logs the warning and sends the Telegram notice, but the new value won’t take effect until you restart.

To restart, send /restart in Telegram (when a service manager relaunches Untether), or restart the service directly. The restart notice names the unit or launchd label of the instance that’s running; the default is:

systemctl --user restart untether                         # Linux (systemd), default unit
launchctl kickstart -k gui/$(id -u)/<your-launchd-label>  # macOS (launchd)

transports.telegram#

untether config

untether config set transports.telegram.bot_token "..."
untether config set transports.telegram.chat_id 123

toml

[transports.telegram]
bot_token = "..."
chat_id = 123

When allowed_user_ids is set, updates without a sender id (for example, some channel posts) are ignored.

transports.telegram.topics#

🔄 Restart-required as a whole section — changes to either key only take effect after a restart because topic initialisation runs at startup.

transports.telegram.files#

Default deny_globs:

deny_globs = [
  ".git/**", ".env", "**/.env", "**/.env.*", ".envrc", "**/.envrc",
  "**/*.pem", "**/*.key", "**/id_rsa", "**/id_ed25519", "**/.ssh/**",
  "**/.netrc", "**/.npmrc", "**/.pypirc",
]

File size limits (not configurable):

• uploads: 20 MiB
• downloads / outbox: 50 MiB

projects.<alias>#

untether config

untether config set projects.happy-gadgets.path "~/dev/happy-gadgets"
untether config set projects.happy-gadgets.worktrees_dir ".worktrees"
untether config set projects.happy-gadgets.default_engine "claude"
untether config set projects.happy-gadgets.worktree_base "master"
untether config set projects.happy-gadgets.chat_id -1001234567890

toml

[projects.happy-gadgets]
path = "~/dev/happy-gadgets"
worktrees_dir = ".worktrees"
default_engine = "claude"
worktree_base = "master"
chat_id = -1001234567890

Legacy config note: top-level bot_token / chat_id are auto-migrated into [transports.telegram] on startup.

Plugins#

plugins.enabled#

untether config

untether config set plugins.enabled '["untether", "untether-transport-slack", "untether-engine-acme"]'

toml

[plugins]
enabled = ["untether", "untether-transport-slack", "untether-engine-acme"]

• enabled = [] (default) means “load all installed plugins”.
• If non-empty, only distributions with matching names are visible (case-insensitive).

plugins.<id>#

Plugin-specific configuration lives under [plugins.<id>] and is passed to command plugins as ctx.plugin_config.

footer#

Controls what appears in the message footer after a run completes.

toml

[footer]
show_api_cost = false
show_subscription_usage = true

When show_subscription_usage is enabled, a compact line like ⚡ 5h: 45% (2h 15m) | 7d: 30% (4d 3h) appears after every Claude Code run. Threshold-based warnings (≥70%) appear regardless of this setting.

preamble#

Controls the context preamble injected at the start of every agent prompt.

toml

[preamble]
enabled = true
text = "Custom preamble text..."

The default preamble tells agents they’re running via Telegram, lists key constraints (only assistant text is visible), and requests a structured end-of-task summary.

progress#

Controls progress message rendering during agent runs.

toml

[progress]
verbosity = "verbose"
max_actions = 8
heartbeat_interval = 30

Per-chat override: /verbose on and /verbose off override the config default for the current chat without editing the TOML file. /verbose clear removes the override.

Hot-reload

Editing [progress] in untether.toml applies on the next run without restart (#269). The default presenter and per-chat /verbose overrides both pick up the new values. The background-task keys are re-read at each turn of a live session and on each status-message refresh.

cost_budget#

toml

[cost_budget]
enabled = true
max_cost_per_run = 2.00
max_cost_per_day = 10.00
warn_at_pct = 70
auto_cancel = false
warn_run_above_usd = 20.00
notify_run_outlier = true

Budget alerts always appear regardless of [footer] settings.

The outlier alert works with no budget configured

Everything above warn_run_above_usd is gated on enabled = true, so a deployment with no [cost_budget] block gets no spend signal at any amount — the one configuration where an alarm matters most (#702). The per-run outlier alert is deliberately independent: it logs cost.run_outlier and adds one chat line for any single run above the threshold (default US$20), whatever [footer] show_api_cost is set to. Set notify_run_outlier = false to keep the log without the chat line.

Cumulative session cost is not capped

Sessions can stack many runs via /continue, follow-up prompts, or a long back-and-forth dogfooding chat. A single session has been observed to cumulate over US$100 across 5 sub-runs even though each individual run was well under max_cost_per_run (#517). If you need a ceiling that spans sessions, set max_cost_per_day — Untether tracks daily cost across all sessions and triggers cost_budget.exceeded once the day’s spend crosses it. A max_cost_per_session knob is not currently provided; file a feature request if your workflow needs one.

Since v0.36.0, Claude run costs are per run: Claude reports a running total for the whole session, and Untether records the difference since the previous run in session_costs.json. Earlier versions counted a resumed session’s whole history against each run’s budget, /stats and daily total (#778).

watchdog#

toml

[watchdog]
liveness_timeout = 600.0
stall_auto_kill = false
stall_repeat_seconds = 180.0
reap_orphans = true
tool_timeout = 600.0
mcp_tool_timeout = 900.0
subagent_timeout = 900.0
detect_unanswerable_control_requests = true
detect_stuck_after_tool_result = false
stuck_after_tool_result_timeout = 300.0
stuck_after_tool_result_recovery_enabled = true
stuck_after_tool_result_recovery_delay = 60.0
detect_catalog_staleness = true
notify_catalog_refresh = false
catalog_refresh_min_interval_s = 5.0
prespawn_ram_warn_mb = 2000
prespawn_ram_block_mb = 500
prespawn_ram_per_run_reserve_mb = 750
max_concurrent_engine_runs = 0
claude_stream_idle_timeout_ms = 300_000
stream_idle_auto_retry = false
stream_idle_max_retries = 1
post_result_idle_enabled = true
post_result_idle_timeout = 600.0
bash_grace_seconds = 60.0
pre_result_silence_timeout = 3600.0
post_result_limbo_grace = 60.0
post_result_bg_max_hold = 1800.0
bg_hold_rearm_on_progress = true
bg_hold_declared_waits = true
live_sessions = true
live_session_max_s = 14400.0
rearm_plan_mode = true
hold_for_async_hooks = true
async_hook_max_hold = 630.0

The post-result watchdog is a permanent mitigation (#569)

post_result_idle_*, the SIGTERM/SIGKILL subcountdown, and detect_stuck_after_tool_result are not transitional workarounds. Both upstream defects they mitigate — claude-code#39700 (stream-json hangs and never exits) and claude-code#30333 (ResultMessage never emitted) — are CLOSED / NOT_PLANNED. Disabling these knobs re-exposes hung sessions that never terminate, and the post-result limbo SIGTERM additionally bounds the MCP-child leak tracked in #590 / #592. See Claude runner reference.

The stall monitor in ProgressEdits fires at 5 min (300s) idle, 10 min for local tools (tool_timeout), 15 min for MCP tools (mcp_tool_timeout) and active child processes (subagent_timeout; outside Claude Code only while the process tree is using CPU, so a permanent wrapper or MCP-server child doesn’t count, #953), and for pending approvals after 10 min, then every 30 min. Sessions blocked on an unanswered approval, inside an upstream rate-limit window (a rejected quota snapshot, #790), or in a Claude CLI API-retry back-off (#792) are treated as expected waits (#495/#499/#500): they log a paced subprocess.approval_pending INFO instead of a progress_edits.stall_detected WARNING, are excluded from the frozen-ring escalation, and do not count toward the stall_warnings metric reported in session.summary. When a local tool is running and the child process is CPU-active, the first stall warning fires but repeat warnings are suppressed — they resume if CPU goes idle (indicating a genuinely stuck tool). A stopped (state T) or I/O-blocked (D) engine process is reported as ⏳ Engine process is stopped … / … blocked on I/O … rather than as idle child processes (#953). The liveness watchdog in the subprocess layer fires at liveness_timeout with /proc diagnostics. When stall_auto_kill is enabled, auto-kill requires a triple safety gate: timeout exceeded + zero TCP connections + CPU ticks not increasing between snapshots.

[loop]#

Controls how Untether handles Claude Code’s scheduling tools (CronCreate, ScheduleWakeup). With Loop mode on (opt in per chat via /config → 🔁 Loop mode), Untether runs Claude’s schedules itself, with the caps below. With it off, Claude can’t schedule recurring or timed tasks. (#289, #925)

toml

[loop]
enabled = false
inline_threshold_seconds = 300
redundancy_check_interval = 30
max_iterations = 20
max_total_duration_hours = 4
min_interval_seconds = 60
expiry_days = 7
own_schedule = true

Cost limits are NOT in [loop] — they live in [cost_budget] and apply to loop fires automatically. See Cost budgets for setup.

State is persisted to active_loops.json (sibling of your untether.toml) so loops survive restarts. Alongside it are the per-loop cancel records and the sessions that may still hold an older Claude-side scheduled task; those resume with CLAUDE_CODE_DISABLE_CRON=1 for up to 7 days so the task can’t restart (#926).

Rolling back to 0.35.4 (or 0.35.5rc19 and earlier)

Older versions reject any config key they don’t know, in every section, not just [loop]. Remove own_schedule and the other keys added in v0.36.0, and change plan-auto back to auto, before downgrading, or the config won’t load. See Rolling back to 0.35.4 for the full list.

[auto_continue]#

Auto-continue detects when Claude Code exits after receiving tool results without processing them (upstream bugs #34142, #30333) and automatically resumes the session. Detection is based on a protocol invariant: normal sessions always end with last_event_type=result, while premature exits show last_event_type=user.

Auto-continue only fires on a clean exit (rc=0). Signal deaths (rc=143/SIGTERM, rc=137/SIGKILL) and ordinary failures are excluded, to prevent death spirals under memory pressure (#640).

This section also carries the empty-resume recovery and session-ownership knobs, since they mitigate the same upstream turn-state family.

toml

[auto_continue]
enabled = true
max_retries = 1
resend_empty_resume = true
empty_resume_fresh = true
quarantine_on_forced_teardown = true
serialize_session_owner = true
session_handoff_timeout_s = 30.0
session_handoff_bg_timeout_s = 600.0

Layered defence

serialize_session_owner is proactive (stop the session being poisoned); quarantine_on_forced_teardown and empty_resume_fresh are reactive (recover once it has been). Leave all three on unless you are bisecting a regression.

[security]#

Runtime security knobs. Defaults are safe — operators only flip these when investigating a leak or opting out of a probe.

toml

[security]
env_audit = true
env_extra_allow = ["OP_SERVICE_ACCOUNT_TOKEN", "DOPPLER_TOKEN"]
env_extra_prefix_allow = ["VAULT_", "INFISICAL_"]

Engine-specific config tables#

Each engine reads a table keyed by its id, written either as [engines.<id>] (e.g. [engines.claude]) or as a top-level [<id>] (e.g. [claude]). The two layouts don’t mix: once an [engines] table exists (even an empty one, or a single [engines.<id>]), every flat [claude] / [codex]-style table is ignored (UntetherSettings.engine_config). Built-in engines are listed here; plugin engines should document their own keys.

An invalid engine table stops Untether from starting when it belongs to the default engine. For any other engine the table is ignored with a setup.warning log and the engine runs on its defaults — except a refused extra_args flag, which disables that engine (listed under failed to load: in the startup message) rather than dropping its other settings.

codex#

untether config

untether config set codex.extra_args '["-c", "notify=[]"]'
untether config set codex.profile "work"

toml

[codex]
extra_args = ["-c", "notify=[]"]
profile = "work"

claude#

untether config

untether config set claude.model "claude-sonnet-5-5"
untether config set claude.allowed_tools '["Bash", "Read", "Edit", "Write"]'
untether config set claude.extra_args '["--chrome"]'
untether config set claude.dangerously_skip_permissions false
untether config set claude.use_api_billing false

toml

[claude]
model = "claude-sonnet-5-5"
allowed_tools = ["Bash", "Read", "Edit", "Write"]
extra_args = ["--chrome"]    # e.g. opt into Claude-in-Chrome
dangerously_skip_permissions = false
use_api_billing = false

pi#

untether config

untether config set pi.model "..."
untether config set pi.provider "..."
untether config set pi.extra_args "[]"

toml

[pi]
model = "..."
provider = "..."
extra_args = []

opencode#

untether config

untether config set opencode.model "anthropic/claude-sonnet-5-5"

toml

[opencode]
model = "anthropic/claude-sonnet-5-5"

gemini#

Deprecated — no longer supported

The Gemini CLI engine still loads but is deprecated and no longer supported: it gets no fixes, is excluded from testing, and may be removed in a future release. The CLI has reached end of life upstream for individual accounts and hangs under Untether until the watchdog cancels the run. Plan a move to another engine.

untether config

untether config set gemini.model "gemini-2.5-pro"
untether config set gemini.skip_trust true

toml

[gemini]
model = "gemini-2.5-pro"
skip_trust = true

Approval mode

Gemini CLI’s approval mode (read-only / edit files / full access) is toggled per chat via /config → Approval mode, not the config file. Codex CLI’s approval policy (full auto / safe) is similarly toggled via /config → Approval policy: safe runs codex exec with --sandbox read-only (no --ask-for-approval, which codex exec ignores — #830), and full auto adds no sandbox flag. See inline settings.

amp#

Deprecated — no longer supported

The AMP engine still loads but is deprecated and no longer supported: it gets no fixes, is excluded from testing, and may be removed in a future release. The AMP backend refuses Untether’s runs (HTTP 426). Plan a move to another engine.

untether config

untether config set amp.mode "deep"
untether config set amp.dangerously_allow_all true

toml

[amp]
mode = "deep"
dangerously_allow_all = true

Triggers#

Webhook and cron triggers that start agent runs from external events. See the full Triggers reference for auth, templating, and routing details.

toml

[triggers]
enabled = true

[triggers.server]
host = "127.0.0.1"
port = 9876
rate_limit = 60
max_body_bytes = 1_048_576

[[triggers.webhooks]]
id = "github-push"
path = "/hooks/github"
project = "myapp"
engine = "claude"
auth = "hmac-sha256"
secret = "whsec_abc..."
prompt_template = "Review push to {{ref}} by {{pusher.name}}"

[[triggers.crons]]
id = "daily-review"
schedule = "0 9 * * 1-5"
project = "myapp"
engine = "claude"
prompt = "Review open PRs and summarise status."

[triggers]#

Hot-reload

When watch_config = true, changes to webhooks, crons, schedules, and timezones are applied automatically without restart. [triggers.server] settings (host, port, rate_limit, max_body_bytes) and turning enabled on still require a restart. See the Triggers reference — Hot-reload for details.

[triggers.server]#

[[triggers.webhooks]]#

[[triggers.crons]]#