Operate

Upgrades & troubleshooting.

Everything you need once DayMug is running: service commands, one-click upgrades with automatic rollback, logs, backups, and a table of the problems people actually hit.

Service commands

Task	Linux (systemd user unit)	macOS (LaunchAgent)
Start	`systemctl --user start daymug.service`	starts automatically when the user logs in
Restart (after editing config)	`systemctl --user restart daymug.service`	`launchctl kickstart -k "gui/$(id -u)/com.daymug.daymug"`
Status	`systemctl --user status daymug.service`	`launchctl print "gui/$(id -u)/com.daymug.daymug"`
Stop	`systemctl --user stop daymug.service`	`launchctl bootout "gui/$(id -u)/com.daymug.daymug"`

On Linux the installer registers the unit but does not enable it at boot, so after a reboot you start it again. To have it start on its own, enable it and let the user's services run without an open login session:

systemctl --user enable daymug.service
sudo loginctl enable-linger "$USER"

On macOS the LaunchAgent only runs while the installing user is logged in — a Mac sitting at the login screen won't serve DayMug.

Running it by hand

Installed with --skip-service, or running under your own supervisor? Start with ~/.daymug/daymug serve and stop with Ctrl-C or ~/.daymug/daymug stop (it only stops the instance this binary started).

A plain kill is ignored

Agents run as the same OS user as DayMug, so a stray pkill from an agent could otherwise take the whole server down. A bare SIGTERM is therefore logged and ignored (systemctl stop/restart and the macOS LaunchAgent are unaffected). Supervisors that only send SIGTERM — supervisord, pm2, container runtimes — need DAYMUG_HONOR_SIGTERM=1 in the environment.

Upgrade

Admins open Settings → Administration → Global and click Check for updates. DayMug downloads the new binary, verifies its SHA-256, swaps it in atomically and restarts. A watchdog then polls /api/health; if the new version isn't healthy within upgrade.health_timeout (60 s), the previous binary is restored automatically.

~/.daymug/daymug upgrade                     # latest release
~/.daymug/daymug upgrade --version v1.2.3    # a specific tag (also downgrades)
~/.daymug/daymug upgrade --rollback          # back to the previous binary
~/.daymug/daymug version

Re-running the one-line installer also upgrades in place and keeps your config.yaml. Running under a different unit name or a root-level systemd unit? Adjust the upgrade block. Started by hand with daymug serve? The binary is still replaced, but nothing restarts it — restart it yourself.

Logs

tail -f ~/.daymug/logs/daymug.log                     # always there; rotated at 32 MiB, 5 kept
journalctl --user -u daymug.service -f                # Linux — note the --user
log stream --predicate 'process == "daymug"'          # macOS

journalctl -u daymug without --user looks at the system manager and shows nothing — the service is a user unit. The startup log prints the effective guardrail values, the Agent SDK version and path, and any SECURITY: warnings.

Back up and move

All state lives under ~/.daymug/: the binary, config.yaml, data/database.db (conversations, users, provider accounts, bot tokens) and users/ (everyone's work directories). Provider logins live in the credential directories you chose for each account.

systemctl --user stop daymug.service
tar czf daymug-backup-$(date +%F).tgz -C ~ .daymug
systemctl --user start daymug.service

To move to a new machine, restore the archive into the same home path, install the prerequisites, and run ~/.daymug/daymug bootstrap to register the service again. Treat the archive as secret — it contains credentials.

Troubleshooting

Symptom	Fix
Service exits right after start	Read the last lines of `~/.daymug/logs/daymug.log` — usually a config error. See startup errors.
Claude Agent SDK missing	`npm install -g @anthropic-ai/claude-agent-sdk`. Installed somewhere unusual? Set `DAYMUG_CLAUDE_AGENT_SDK_MODULE` to the absolute path of `sdk.mjs`.
“a claude-compatible provider requires the Claude CLI”	Install or upgrade `claude`: `npm install -g @anthropic-ai/claude-code`.
Codex or `app-server` missing	`npm install -g @openai/codex`, then check `codex app-server --help`.
A new chat says no provider is available	Add an account in Providers & models and bind it to the user in the Users page.
Model picker is empty	The account has no models — add model ids and a summary model.
Saving a Codex account: “config_dir required”	Codex-family accounts need a credential directory (`CODEX_HOME`).
Can't log in over HTTP after enabling HTTPS settings	`auth.cookie_secure: true` makes browsers drop the cookie on plain HTTP. Set it back to `false` or use HTTPS.
Chat disconnects behind a proxy	Forward WebSocket headers (`Upgrade`, `Connection`) and set `proxy_read_timeout` ≥ 3600s.
Notification taps don't open the conversation	Set `server.public_url`.
Every admin got demoted	Add your username to `admin.bootstrap_usernames`, restart.
Forgot a password	`~/.daymug/daymug user passwd <username>`
Sandbox enabled but agents still see everything	`bwrap` isn't installed (look for `SECURITY:` in the log), or the user is set to Unrestricted, or they're an admin.
Upgrade left the site down	The watchdog rolls back on its own; if not, `~/.daymug/daymug upgrade --rollback`.
Container / supervisor can't stop DayMug	Set `DAYMUG_HONOR_SIGTERM=1`, or stop it with `daymug stop` / SIGINT.
Nothing running after a reboot	Linux: `systemctl --user start daymug.service` (or enable it, above). macOS: log in as the installing user.

Still stuck? Open an issue on GitHub with your OS, daymug version and the relevant log lines (remove tokens and secrets first).