AgentsDock

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.

Applies to AgentsServer 1.0.x releases. Source of truth: the AgentsServer repository and ./install.sh --help.

Requirements

Installer options

./install.sh [--port PORT] [--bind ADDRESS] [--release-version VERSION]
             [--non-interactive] [--allow-port-fallback | --no-port-fallback]
             [--show-token] [--instance NAME]

Every run is idempotent: it keeps the previous healthy release for rollback, preserves the access token and configuration, and never touches chat state. A failed run leaves the active release unchanged and prints recovery guidance. An install lock stops a cancelled SSH attempt from racing a retry.

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.

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)

Remote access is expected to go through Tailscale, which keeps the server reachable from phones, tablets, and laptops without publishing the port on the internet. It is optional; the installer only prints a reminder if Tailscale isn't on the host.

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 and prints it once. It is required for every HTTP call, upload, file/video fetch, and WebSocket stream. Retrieve it any time with:

./install.sh --show-token

Clients send it as Authorization: Bearer <token> (or the X-AgentsDock-Token header). When running the server manually, set AGENTSDOCK_AGENT_TOKEN yourself; leave it unset only for trusted local development.

Manual install & run

If you'd rather not use the installer or the service, run the server directly from a checkout:

git clone https://github.com/ZhengyiLuo/AgentsServer.git
cd AgentsServer
uv venv
uv sync --frozen

# confirm the CLIs work in this same shell/user
command -v claude && claude --version
command -v codex  && codex --version

export AGENTSDOCK_AGENT_TOKEN='replace-with-a-long-random-token'
uv run python agent_server.py serve --bind 0.0.0.0 --port 7850

Check it from the server machine:

curl -H 'Authorization: Bearer replace-with-a-long-random-token' http://127.0.0.1:7850/api/health

Use AGENTSDOCK_STATE_DIR to keep state somewhere other than ~/.agentsdock, and AGENTSDOCK_BACKEND if you only install one of the CLIs.

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

Paths

Backends

Jobs & guardrails

Context digests

File locations

Named instances use sibling paths of their own — see Where each instance lives.