AgentsDock

Server reference

Multiple servers on one machine

One machine, one user account, several fully independent AgentsServers — each with its own port, service, token, chat history, and terminals. Useful for separating work and personal, running a beta next to stable, or giving each project its own server.

Availability

Not yet in a published release. Named instances are on the AgentsServer main branch (merged 20 Sep 2026). They are not in v1.0.3 or v1.0.4-beta.9. Until a release ships them, you need a server installed from a main checkout. Check the release notes for the first version that includes them.

How instances work

Your first server is the default instance — it keeps the paths, service name, and port you already have. Each additional server is a named instance (work, beta, …) with its own service, port, configuration, state directory, logs, and tmux server, installed as siblings of the default. Nothing is shared, and removing the default can never remove a named instance.

Instances are independent services for convenience — they are not a security boundary between each other, since they all run as your user account.

Create an instance

From an AgentsServer checkout on main:

# automatic name and the next free port (7851 upwards)
./instances.sh new

# or choose the name and port
./instances.sh new --name work --port 7851

# optional bind address (default 0.0.0.0)
./instances.sh new --name lab --port 7852 --bind 0.0.0.0

A new instance starts with an empty chat list and its own freshly generated access token. Names are lowercase: a letter followed by up to 31 letters, digits, or hyphens.

List & connect

./instances.sh list        # name, status, port (also the default action)
./instances.sh info work   # details for one instance

Connect the app to an instance exactly like any server — its URL is your host address plus that instance's port, and its token comes from:

./install.sh --instance work --show-token

Add several instances to the app and switch between them from the server switcher.

Update an instance

Each instance updates independently; add --instance to the normal update command:

git pull --ff-only
./install.sh --instance work

./install.sh with no --instance updates only the default server. All other installer options (--port, --bind, --release-version, …) work per instance — see Installer options.

Where each instance lives

Replace NAME with the instance name.

The default instance keeps the standard paths listed in File locations.

Terminals per instance

Each named instance runs its chat terminals on its own tmux server, so they never mix with the default server's sessions or with anything else you run in tmux:

tmux ls                             # default server's chat terminals (zd_*)
tmux -L agents-server-work ls       # the 'work' instance's terminals (zdi_work_*)

Remove an instance

./uninstall.sh --instance work            # one instance
./uninstall.sh --all                      # every instance, including default
./uninstall.sh --all --exclude default    # every named instance, keep default

Running ./uninstall.sh with no arguments lists your instances and asks you to confirm their exact names. Removal stops the service and deletes the runtime and configuration (including that instance's token); its chat history is preserved by default. When a name is released, its state directory is moved to a private backup, not erased — see Name-release backups. --purge-state is the only destructive option and always requires typing the exact path.

Rules & limits