Skip to main content
Running Overdeck day to day means knowing how to stop everything in an emergency, what a low-disk alert means, when to reload versus restart, how a restart hold and approval gate work together, what comes back after a crash, and what is and is not backed up. This page covers all of it in one place.

Stop every agent now

Emergency stop kills every running agent across all harnesses right away. Nothing it kills is deleted; work in progress is simply cut off. You can trigger it five ways:
  • The hotkey Ctrl+Shift+. (Cmd+Shift+. on macOS, see Keyboard shortcuts), which works even while typing in a text field. It opens a confirm dialog: press Enter to stop all agents, or Esc to cancel.
  • The top bar’s Agents menu, “Stop all agents…”, which opens the same confirm dialog. The item is unavailable while no agents are working.
  • The command palette’s “Emergency Stop All Agents” action, which opens the same confirm dialog.
  • The System Health popover, under System controls: a stop button with an inline “Kill all?” confirm.
  • From a terminal, run pan admin cloister emergency-stop. It prints the agents it stopped and warns about any it could not confirm stopped.
Stopping also freezes auto-resume for crashed agents, so nothing restarts on its own while you are dealing with the emergency. The freeze survives a restart. To undo it, click the “Auto-resume frozen” chip (snowflake icon) in the top bar, or use the Auto-resume toggle in the System Health popover. Emergency stop also stops Cloister’s health monitoring: start it again with Start Cloister in the System Health popover or the command palette, or with pan admin cloister start. Emergency stop is not the same as Safe shutdown. Safe shutdown lets each agent finish its current step before stopping; emergency stop kills every agent now.

Low-disk alerts

Overdeck checks free space on the filesystem holding ~/.overdeck every 30 seconds. Two thresholds control it: resources.disk_warn_gb and resources.disk_critical_gb in ~/.overdeck/config.yaml. See Memory governor for the keys table and their defaults. When free space drops below a threshold, Overdeck sends one phone push (titled “Disk low” or “Disk critical”, following the phone Failures switch described in Push notifications) and, at the critical level, a desktop notification too. Needs you shows a Disk low or Disk critical card listing the biggest folders and an Open Resources button, which opens the Resources view (experimental: turn on Settings → Experimental → Experimental features to show it). A critical alert only sorts into the Blocking group; it does not stop or hold anything, and the auto-resume freeze from emergency stop does not affect it. A separate, fixed 10 GiB disk floor refuses new workspace starts, workspace stack rebuilds and lane launches, regardless of the alert thresholds above. See Troubleshooting for what gets held and why, and Lanes for pan lane disk-check, which checks the floor before a launch wave or a worktree you create yourself.

pan reload or pan restart

Use pan reload to ship new code: it builds from origin/main, checks the build, waits for restart approval, then restarts. If the build check fails, the old dashboard keeps running untouched. If it passes, the old dashboard stops before the new one starts; if the new dashboard then fails its own startup health check, the old one is not restored, and the new one is either already gone or left running for inspection. pan reload refuses during a safe-shutdown drain and while a restart hold is active. Use pan restart to relaunch the build you already have: it never builds. It can target just the dashboard (the default), CLIProxy, Traefik, or the full stack. Only the dashboard and full scopes wait for restart approval and obey a restart hold. pan reload keeps the running dashboard’s auto-resume setting unless you pass --resume or --no-resume. pan restart turns auto-resume on unless you pass --no-resume or the shell running it sets OVERDECK_NO_RESUME=1. See Core commands for the full flag tables.

Restart approval and the restart hold

Approving a restart

Every voluntary dashboard restart (pan reload, a dashboard or full-scope pan restart, and the post-merge deploy) waits for your approval before it runs. One approval satisfies every request waiting at that moment, with a single restart. If the running dashboard build has no restart gate, or its health check keeps failing for 60 seconds, the restart proceeds without approval. Approve with the “Restart now” button on the dashboard’s approval banner, with pan restart approve, or with pan restart --now, which approves and restarts in one step.

Holding restarts

A restart hold refuses every voluntary restart until you release it:
--reason is required; --until takes a duration such as 30m, 2h, 1d, or an ISO time in the future. While a hold is active, the approval banner shows “Restarts on hold” with the reason and a lock icon instead of a button, and pan restart --now cannot bypass it. The hold does not block the CLIProxy or Traefik scopes, or the supervisor’s own watchdog restart. On release, Overdeck tells you that a reload refused during the hold was not queued, so run pan reload again to ship whatever merged while the hold was active.

After a crash or reboot

A work agent whose pane dies with no recorded stop is resumed automatically, but only when all of the following hold: it was seen dead on two checks at least 45 seconds apart, nobody stopped it on purpose, it is not paused, troubled, or in failure backoff, its issue is open and not merged, auto-resume is not frozen, the dashboard was not started with --no-resume, and memory pressure is normal. At most one resume happens every 45 seconds, oldest crash first, with one attempt per crash. If a resume fails, Needs you reports it and tells you to run pan resume <id>. Turn auto-resume off for a boot with pan up --no-resume or pan restart --no-resume; the emergency-stop freeze also stops it. Conversations are never auto-resumed. After a terminal-backend restart, Needs you offers to resume the conversations that were running, listed in Conversations. After pan shutdown, Needs you instead offers to resume the sessions the shutdown drain stopped, described in Safe shutdown. To resume things by hand, see pan resume and pan recover.

Backups

Overdeck backs up the ~/.claude/skills, ~/.claude/commands and ~/.claude/agents folders that pan sync writes. pan context detach --apply backs up each native CLAUDE.md or AGENTS.md file before it removes a managed region from it. Nothing backs up the Overdeck database or the rest of ~/.overdeck state. To keep conversation transcripts off this machine, see Session Vault. pan sync backs up those folders first and keeps the newest 10 backups. Under [sync] in ~/.overdeck/config.toml, set backup_before_sync = false to turn that off, or backup_keep to keep a different number. pan sync --backup-only makes the backup without syncing, but only while backup_before_sync is on: with it off, the flag is ignored and a full sync runs. Every pan sync run, --backup-only included, first removes the skills that the 0.7.0 upgrade renamed or deleted from ~/.claude/skills/, before the backup is taken, so copy a customized version of one of them elsewhere first. You can also manage backups directly:
pan restore with no timestamp lists the newest backups to choose from, and always asks for confirmation before replacing the target folder. Today it restores the skills and commands folders only: the agents folder is backed up, but pan restore does not bring it back.

Get help

Join the Overdeck Discord or file an issue on GitHub Issues.