Operations and monitoring
Untether runs as a long-lived process, typically in a terminal or managed by a process supervisor (systemd on Linux, etc.). This guide covers health checks, ...
Untether runs as a long-lived process, typically in a terminal or managed by a process supervisor (systemd on Linux, etc.). This guide covers health checks, graceful restarts, diagnostics, and day-to-day operations — all controllable from Telegram without SSH.
Health check
Send /ping in Telegram to verify the bot is running:
Untether pong — up 3d 14h 22m
The response includes the bot’s uptime since last restart. Use this as a quick liveness check.
If webhooks and cron are enabled, the webhook server also exposes a health endpoint:
GET http://127.0.0.1:9876/healthReturns {"status": "ok", "webhooks": N} where N is the number of configured webhooks. Useful for external monitoring tools.
Graceful restart
Send /restart in Telegram to initiate a graceful shutdown:
- Untether stops accepting new runs
- Active runs are drained (allowed to finish)
- The process exits cleanly
- Run
untetheragain in your terminal (or your process supervisor restarts it automatically)
Prefer /restart over killing the process
/restartlets in-progress runs complete before shutting down. Killing the process withkillorsystemctl restartmay interrupt active runs and lose work.
SIGTERM behaviour
Sending SIGTERM to the Untether process triggers the same graceful drain as /restart:
- New runs are rejected
- Active runs are allowed to complete
- After a 120-second drain timeout, remaining runs are cancelled and the process exits
This means systemctl --user stop untether (Linux) also drains gracefully, as systemd sends SIGTERM first. Pressing Ctrl+C in a terminal sends SIGINT, which triggers the same graceful drain.
Drain timeout The default drain timeout is 120 seconds. If active runs don’t complete within this window, they are cancelled and a timeout notification is sent to Telegram.
Run diagnostics
Run the built-in preflight check to validate your configuration:
untether doctorThis validates:
- Telegram bot token is valid and the bot is reachable
- Chat ID is correct and the bot can send messages
- Topics configuration (if enabled)
- File transfer permissions and deny globs
- Voice transcription setup
- Engine availability (Claude Code, Codex, OpenCode, Pi, Gemini CLI, Amp)
Run this after any config change, after upgrading, or when something isn’t working.
Debug mode
Start Untether with debug logging to troubleshoot issues:
untether --debugThis logs detailed information to debug.log, including:
- Engine JSONL events (every line from the subprocess)
- Telegram API requests and responses
- Rendered messages and inline keyboards
- Config loading and validation
Check debug.log first When reporting issues, include the relevant section of
debug.log. It contains everything needed to diagnose most problems.
Config hot-reload
Enable config watching so Untether picks up changes without a restart:
=== “untether config”
```sh
untether config set watch_config true
```=== “toml”
```toml title="~/.untether/untether.toml"
watch_config = true
```When enabled, Untether watches the config file for changes and reloads most settings automatically. Transport settings (bot token, chat ID) are excluded — those require a full restart.
Process management
=== “Telegram (all platforms)”
Send `/restart` in Telegram for a graceful restart with drain visibility.
Use `/ping` to check the bot is running.=== “Terminal (all platforms)”
Stop with Ctrl+C (if running), then:
```sh
untether
```
View output directly in the terminal. Use `--debug` for verbose logging to `debug.log`.=== “Linux (systemd)”
```bash
systemctl --user restart untether
journalctl --user -u untether -f # live logs
systemctl --user status untether # check status
journalctl --user -u untether -n 100 # recent logs
```Restart vs /restart
systemctl --user restart untethersends SIGTERM, which triggers a graceful drain. However,/restartin Telegram gives you a confirmation message and visibility into the drain process. Prefer/restartwhen you have Telegram access — it works on all platforms.
Related
- Troubleshooting — common issues and debugging strategies
- Configuration — full config reference
- Dev setup — running from source for development
- Security hardening — securing your instance
