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 Install & update Access token Check it's running Start, stop, restart Uninstall Settings & file locations

Help

Report an issue

Server reference

Advanced install Multiple servers Back up & uninstall

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.

AgentsServer on GitHub →

Looking for every installer option, environment variable, multiple servers on one machine, or backups? See the Server reference.

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 (default 7850).
  • --bind ADDRESS — bind address (default 0.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.

Example output:

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/current points at the active one.
  • ~/Library/Logs/AgentsServer/ (macOS) or journalctl --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, claude or codex.
  • CLAUDE_BIN / CODEX_BIN — path to each CLI if it isn't on PATH.

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.

AgentsDock

An IDE designed for agentic AI research.© 2026 AgentsDock

Docs Support Report an issue Privacy Discord ↗