Docs
Manage your server
AgentsServer is the open-source backend that runs on your own machine. Everything below is done from a terminal on that machine — the server, not the device running the app.
No sudo is ever needed. The installer runs as your user, keeps the previous healthy release for rollback, and preserves your chat history, jobs, files, and access token across every update.
Install & update
Before installing: use macOS (Apple silicon) or Linux with Node.js 22.14 or later, npm, and uv on the server machine. AgentsDock does not install uv automatically. On macOS with Homebrew, run brew install uv; for Linux or other methods, see the official uv installation guide.
Confirm uv --version works in the same terminal, then install the AgentsDock CLI as the user who will own the server:
npm install -g agentsdock
On a fresh machine, the global install creates the default user service and installs the runtime under ~/.local/share/agents-server. No repo clone is needed. Do not use sudo. A local npm install agentsdock only adds a project dependency; it does not create a server service.
After installation, run agentsdock list to confirm default is running and find its URL, then agentsdock token default to read its token. npm may hide setup messages; see the connection output example.
To update an existing server, use the app: open Settings → Updates, click Check now, then use Update server or Retry server update when offered. The managed updater swaps in the new runtime, restarts the service, and keeps your token and state.
Custom install options
AGENTSDOCK_SKIP_SETUP=1 npm install -g agentsdock agentsdock setup [--port PORT] [--bind ADDRESS] [--non-interactive] [--dry-run]
--port PORT— pin an exact port (default7850).--bind ADDRESS— bind address (default0.0.0.0, reachable from your other devices).--non-interactive— no prompts; for scripted or SSH-driven runs.--dry-run— print the native installer command without executing it.
Install and sign in to whichever provider CLIs you plan to use on the server. tmux is optional — it powers the in-app terminal and managed updates. If setup reports that uv is required on PATH, see uv troubleshooting.
If an older server update was interrupted during the 1.0.4-era migration, run agentsdock recover on the server machine, then choose Retry server update in the app.
Show your access token
To see the token at any time, run this on the server — it only reads the existing configuration and changes nothing:
agentsdock token default
For a named server, replace default with its name. Run agentsdock token without a name to choose a server interactively.
Paste it into the app's Access token field when adding the server (see the Setup guide).
Check it's running
From the server machine:
agentsdock status
This shows each server instance's status, address, installed version, and port. For one named instance, run agentsdock status NAME. Inside the app, Settings shows the same runtime checks and a Restart server button.
Server (default):
Status: running
Address: http://100.100.100.12:7850 (Tailscale / other networks)
http://192.168.1.23:7850 (Same Wi-Fi / LAN)
http://127.0.0.1:7850 (This machine only)
Version: 1.0.10
Port: 7850
Start, stop, and restart
The installer registers AgentsServer as a user-level service that starts at login. Use the AgentsDock CLI for normal service control:
# default server agentsdock restart default agentsdock stop default agentsdock start default # named instance agentsdock restart work
Most checks should start with agentsdock status or the app's Settings page. If you need raw logs for troubleshooting, use your platform's log viewer:
# macOS tail -f ~/Library/Logs/AgentsServer/server.log tail -f ~/Library/Logs/AgentsServer/server-error.log # Linux journalctl --user -u agents-server.service -f
Uninstall
agentsdock remove default
This stops and removes the service, the versioned runtime, and the generated configuration including the access token. It asks before changing anything (--yes skips the prompt). Your chats, jobs, files, and terminals under ~/.agentsdock are kept, so a later install picks them straight back up.
To delete that state as well, add --purge-state — it always requires typing the exact path to confirm and cannot be undone. Persistent chat terminals are left running as tmux sessions on this server's tmux server; tmux ls lists them. Only close sessions you recognise as this server's chat terminals — other tmux sessions on the machine, and any named server instances (which use their own tmux sockets), are unaffected by uninstalling the default server.
Settings & file locations
Where things live on the server:
~/.agentsdock— chat history, jobs, files, tokens (the state directory).~/.config/agents-server/env— generated service configuration, including the access token.~/.local/share/agents-server/releases/<version>— versioned server releases;~/.local/share/agents-server/currentpoints at the active one.~/Library/Logs/AgentsServer/(macOS) orjournalctl --user(Linux) — logs.
Most settings are environment variables. The ones you're most likely to touch:
AGENTSDOCK_AGENT_PORT/AGENTSDOCK_AGENT_BIND— port (7850) and bind address (0.0.0.0).AGENTSDOCK_AGENT_TOKEN— the shared access token.AGENTSDOCK_STATE_DIR— state directory (~/.agentsdock).AGENTSDOCK_AGENT_CWD— default working directory for new chats (your home).AGENTSDOCK_BACKEND— default backend,claudeorcodex.CLAUDE_BIN/CODEX_BIN— path to each CLI if it isn't onPATH.
The full list, including job concurrency and memory guardrails, is in the server source tree.
Keep it private. Don't expose port 7850 to the public internet. Reach the server over Tailscale or another private network, and leave the access token enabled.