Server reference
Advanced install & configuration
The full reference for installing and configuring AgentsServer. For day-to-day commands (update, token, restart, logs) see Manage your server; for a first-time walkthrough see the Setup guide.
Requirements
- Host: Linux, or Apple-silicon macOS. Intel macOS is not supported; the installer stops before changing anything.
- Node.js/npm for the
agentsdockCLI. Node.js 22.14 or later is required. uvinstalled on the server'sPATHand verified withuv --versionbefore running npm install. It manages the isolated Python environment and dependencies; clients do not need it. On macOS with Homebrew, usebrew install uv. For Linux or other methods, see the official uv installation guide. AgentsDock does not install uv automatically; see troubleshooting if the check fails.- Any provider CLIs you plan to use — Claude Code, Codex, OpenCode, or Cursor — installed and signed in on the host, in the same user account that runs the server.
- tmux (optional) — enables the in-app terminal, live pane inspection, and in-app managed updates. On macOS with Homebrew, the installer offers to install it; otherwise it prints the command and continues.
- Tailscale (highly recommended). Required outside the server's Wi-Fi or local network unless you already have a VPN or private network that lets your devices reach it.
- A working user service session:
launchctl(macOS) orsystemctl --user(Linux). Nosudois ever used.
CLI install options
# standard default setup npm install -g agentsdock # custom setup AGENTSDOCK_SKIP_SETUP=1 npm install -g agentsdock agentsdock setup [--port PORT] [--bind IP] [--non-interactive] [--dry-run]
--port PORT— pin an exact port. Without it the default is7850.--bind ADDRESS— address to listen on. Default0.0.0.0(all interfaces, so other devices can connect).--non-interactive— never prompt (skips the tmux offer and clipboard copy). Use for scripts and SSH-driven runs.--dry-run— print the native installer command without executing it.
The global install sets up a new default user service only when no existing installation or state is present. No repo clone is needed. Existing servers are left unchanged; update them from the app's Settings → Updates. A local npm install agentsdock only adds a project dependency; it does not create a service. The running service never runs from the npm cache.
After installation, use agentsdock token for tokens, agentsdock remove default for removal, and agentsdock new / agentsdock list for named instances. The native helper scripts remain under ~/.local/share/agents-server/current for advanced troubleshooting.
Ports & bind address
If the default port is already held by something that isn't the AgentsServer being replaced, the installer reports the listener (using lsof when available) and picks one of up to five higher free ports. The chosen port is printed at the end of the run.
--portpins that exact port and fails if it's taken.
Bind to 0.0.0.0 (default) to accept connections from other devices; bind to 127.0.0.1 only if the app runs on the same machine. A server bound to loopback is not reachable over Tailscale.
Remote access (Tailscale)
Tailscale is highly recommended for remote access. Outside the server's Wi-Fi or local network, you need it unless you already have a VPN or private network that lets your devices reach the server. On the same local network, you can use the server's local IP address. The installer does not require Tailscale to finish, but that does not make the server reachable from other networks.
On the server:
tailscale status tailscale ip -4
On each device, join the same tailnet and use the server URL:
http://<tailscale-ip>:7850
If a browser on the device can open /api/health but the app can't connect, check that the device is on Tailscale, the URL includes the port, the same access token is entered in the app, and the server is bound to 0.0.0.0 (not only 127.0.0.1).
Never expose port 7850 to the public internet. Use Tailscale or another private network, and keep the access token enabled.
Access tokens
The installer generates a private bearer token. It is required for every HTTP call, upload, file/video fetch, and WebSocket stream. Retrieve it any time with:
agentsdock token
Clients send it as Authorization: Bearer <token> (or the X-AgentsDock-Token header). For a low-level health check from the server machine:
curl -H 'Authorization: Bearer YOUR_TOKEN' http://127.0.0.1:7850/api/health
Service templates
The installer creates and manages the user service for you: the LaunchAgent com.agentsdock.server on macOS, or agents-server.service on Linux. You only need the template below for custom deployments.
mkdir -p ~/.config/systemd/user cp systemd/agents-server.service.example ~/.config/systemd/user/agents-server.service systemctl --user daemon-reload systemctl --user enable --now agents-server.service systemctl --user status agents-server.service --no-pager -l
Start, stop, restart, and log commands for both platforms are on Manage your server.
Environment variables
Most settings are environment variables read by the server. New configurations should use the AGENTSDOCK_* names; historical ZENITHBOT_* / ZENITHDOCK_AGENT_TOKEN names are accepted only as compatibility aliases. Defaults in parentheses.
Network & access
AGENTSDOCK_AGENT_BIND— bind address (0.0.0.0)AGENTSDOCK_AGENT_PORT— port (7850)AGENTSDOCK_AGENT_TOKEN— shared bearer token (unset)
Paths
AGENTSDOCK_STATE_DIR— session, job, and file state (~/.agentsdock)AGENTSDOCK_AGENT_CWD— default working directory for new chats (your home)AGENTS_SERVER_INSTALL_DIR— versioned runtime root (~/.local/share/agents-server)CLAUDE_PROJECTS_ROOT— Claude history search root (~/.claude/projects)CODEX_SESSIONS_ROOT— Codex history search root (~/.codex/sessions)
Backends
AGENTSDOCK_BACKEND— default backend,claudeorcodex(claude)CLAUDE_BIN/CODEX_BIN— executable name or path (claude/codex)AGENTSDOCK_CLAUDE_TRANSPORT— interactive Claude transport:auto,agent-sdk, orprint(auto)AGENTSDOCK_CLAUDE_SDK_IDLE_TTL_SECONDS— idle per-chat SDK client retention (300)AGENTSDOCK_CLAUDE_SDK_MAX_LOADED_CHATS— maximum retained per-chat SDK clients (4)AGENTSDOCK_RUNTIME_CATALOG_TIMEOUT_SECONDS— per-command CLI version/help/model probe timeout (6)AGENTSDOCK_CLAUDE_AUTH_PROBE_TIMEOUT_SECONDS— timeout forclaude auth status(15)AGENTSDOCK_RUNTIME_DIAGNOSTIC_TTL_SECONDS— cache lifetime for CLI version/auth probes (60)
Jobs & guardrails
AGENTSDOCK_JOB_MAX_ACTIVE_RUNS— scheduled-job concurrency cap;0disables (0)AGENTSDOCK_MAX_ACTIVE_AGENT_RUNS— server-wide cap for chat, cron, and goal runs;0= no limit (0)AGENTSDOCK_JOB_MIN_AVAILABLE_MEM_MB— job launch memory guardrail (4096)AGENTSDOCK_MIN_START_AVAILABLE_MEM_MB— interactive launch memory guardrail (2048)AGENTSDOCK_CODE_DIFF_SNAPSHOT_TIMEOUT_SECONDS— max time per isolated Git worktree snapshot (120)
Context digests
AGENTSDOCK_HANDOFF_DIGEST_BACKEND—claudeorcodex(claude)AGENTSDOCK_HANDOFF_DIGEST_MODEL— model (sonnet)AGENTSDOCK_HANDOFF_DIGEST_EFFORT— optional reasoning/effort setting (unset)AGENTSDOCK_HANDOFF_DIGEST_TIMEOUT_SECONDS— summarizer timeout (180)AGENTSDOCK_HANDOFF_DIGEST_CHARS— final digest character cap (56000)
File locations
~/.agentsdock— state: chats, jobs, files, uploads, tokens, secure-peer credentials~/.config/agents-server/env— generated service configuration and the access token~/.local/share/agents-server/releases/<version>— versioned releases;~/.local/share/agents-server/currentpoints at the active one~/Library/Logs/AgentsServer/(macOS) ·journalctl --user -u agents-server.service(Linux) — logs
Named instances use sibling paths of their own — see Where each instance lives.