AgentsDock

Server reference

Back up, restore & uninstall

AgentsServer keeps everything on your machine, in plain directories. This page covers what lives where, how to back it up and bring it back, and exactly what uninstalling removes — and keeps.

Applies to AgentsServer 1.0.x. Named-instance paths and name-release backups require the main build described in Multiple servers.

What is stored where

Your Claude Code and Codex sessions themselves live in those tools' own directories (~/.claude, ~/.codex) and your project files where you keep them — AgentsServer references them but does not own them.

Back up

Only the state and configuration directories matter; the runtime is reinstallable. Stop the server first so files aren't changing mid-copy:

# macOS
launchctl bootout gui/$(id -u)/com.agentsdock.server
# Linux
systemctl --user stop agents-server.service

cp -a ~/.agentsdock ~/agentsdock-backup-$(date +%F)
cp -a ~/.config/agents-server ~/agentsdock-config-backup-$(date +%F)

# then start it again
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentsdock.server.plist   # macOS
systemctl --user start agents-server.service                                           # Linux

For a named instance, use its own service name and the …-instances/NAME paths from Where each instance lives. The configuration backup contains your access token — store it somewhere private.

Restore

In-place state is picked up automatically. If the state directory is still there (as it is after a normal uninstall), simply running ./install.sh again reconnects the same chats, jobs, and files. Reinstalling generates a new access token unless the configuration directory was also kept — update the token in the app if so.

From a copy you made: stop the server, put the backed-up directories back at their original paths, then start it (or run ./install.sh). Restore the configuration directory too if you want to keep the old token.

Reinstalling does not automatically restore a name-release backup — those are handled separately below.

Uninstall

./uninstall.sh                          # lists instances, confirms exact names
./uninstall.sh --instance work          # one named instance
./uninstall.sh --all                    # everything
./uninstall.sh --all --exclude default  # all named instances, keep default
./uninstall.sh --yes                    # skip the prompt (default server)

Uninstalling removes the user service, the versioned runtime, and the generated configuration including the access token. It keeps chat history, jobs, files, secure-peer credentials, and terminals under the state directory, so a later ./install.sh picks the same history back up. It never uses a package manager or sudo, and it refuses to operate on root, home, broad system directories, or overlapping paths.

Name-release backups

When a named instance's name is released (removing it, or creating a fresh instance under that name), its state directory is not deleted — it is moved to a private backup:

~/.config/agents-server-manager/history-backups/<name>-<random>/state

The default instance's name can never be released. Original Claude/Codex chats and your project files are unaffected; only AgentsDock-owned content moves into the backup.

Releasing a name preserves its saved AgentsDock data in the private backup location printed by the command. Reinstalling the instance does not automatically restore that backup, and a reinstalled instance starts with an empty chat list. There is no built-in restore command yet — keep the backup unchanged (don't move or merge it, especially if the name has since been reused) and ask for recovery guidance in Discord or via Report an issue.

Purge state

./uninstall.sh --purge-state

This is the only destructive option. It deletes the state directory — chat history, jobs, files, tokens, secure-peer credentials — permanently. It always asks you to type the exact state path to confirm, and --yes never bypasses that prompt.

Terminal sessions

Uninstalling leaves persistent chat terminals running. They are ordinary tmux sessions, scoped per server:

tmux ls                          # default server: sessions named zd_*
tmux -L agents-server-NAME ls    # named instance: sessions named zdi_NAME_*

Close only the sessions you recognise as AgentsDock chat terminals for the server you removed. Other tmux sessions on the machine, and other instances' sessions, are separate and unaffected.