AgentsDock
Home Docs FAQ Discord
  • English
  • 简体中文

Getting started

Setup guide Client install Connect agents Start your first chat

Guides

Feature guide Chat Agent-to-agent Share Chat Side chat Fork chat Resume chats Workspace Terminal access View & edit code Automation Slash commands Scheduled jobs Keyboard shortcuts Updates Language Manage your server

Help

Report an issue

Server reference

Advanced install Multiple servers Availability How instances work Create an instance List & connect Update an instance Where each instance lives Terminals per instance Remove an instance Rules & limits Back up & uninstall

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

Available in AgentsServer 1.0.9 and later. First install the default server, then use agentsdock new to create additional named services. The initial npm install creates only the default service.

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 the server machine:

# automatic name and the next free port (7851 upwards)
agentsdock new

# or choose the name and port
agentsdock new work --port 7851

# optional bind address (default 0.0.0.0)
agentsdock new 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.

Example output for a named instance:

$ agentsdock new work --port 7851
Create: work:7851
[7/7] AgentsServer 1.0.10 is ready

  Server URL    http://100.100.100.12:7851

AGENTSDOCK_SETUP_RESULT={"server_url":"http://100.100.100.12:7851","access_token":"ad_tok_...","service":"launchd","tailscale_ip":"100.100.100.12","server_version":"1.0.10"}

List & connect

agentsdock list        # name, status, port
agentsdock info work   # details for one instance

Example list output:

NAME                 STATUS     PORT
default              running    7850
  Tailscale / other networks: http://100.100.100.12:7850 (recommended)
  Same Wi-Fi / LAN:          http://192.168.1.23:7850
  This machine only:         http://127.0.0.1:7850

work                 running    7851
  Tailscale / other networks: http://100.100.100.12:7851 (recommended)
  Same Wi-Fi / LAN:          http://192.168.1.23:7851
  This machine only:         http://127.0.0.1:7851

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:

agentsdock token work

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

Update an instance

Each instance updates independently. Use the app's managed update controls for the server connection you want to update. The initial npm install does not create or update named instances.

Where each instance lives

Replace NAME with the instance name.

  • Service: agents-server-NAME (Linux, systemctl --user) · com.agentsdock.server.NAME (macOS LaunchAgent)
  • State (chats, jobs, files, tokens): ~/.agentsdock-instances/NAME
  • Configuration: ~/.config/agents-server-instances/NAME
  • Runtime releases: ~/.local/share/agents-server-instances/NAME
  • Logs: ~/Library/Logs/AgentsServer-instances/NAME/ (macOS) · journalctl --user -u agents-server-NAME (Linux)
  • Registry of all instances: ~/.config/agents-server-manager/instances.json (names, status, ports only — no secrets)

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

agentsdock remove work                  # one instance
agentsdock remove --all                 # every instance, including default
agentsdock remove --all --exclude default # every named instance, keep default

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

  • The default instance cannot be released; only named instances can.
  • Removing the default server never touches named instances (they are sibling roots, not children).
  • Ports must be free and unreserved; the manager never stops an existing listener to take its port.
  • Imported provider history is excluded across instances, so the same Claude/Codex session is not adopted twice.
  • Instances share your user account and are not a sandbox from one another.
AgentsDock

An IDE designed for agentic AI research.© 2026 AgentsDock

Docs Support Report an issue Privacy Discord ↗