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 Requirements Installer options Ports & bind address Remote access (Tailscale) Access tokens Service templates Environment variables File locations Multiple servers Back up & uninstall

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 source tree, agentsdock --help, and the installed native helper scripts.

Requirements

  • Host: Linux, or Apple-silicon macOS. Intel macOS is not supported; the installer stops before changing anything.
  • Node.js/npm for the agentsdock CLI. Node.js 22.14 or later is required.
  • uv installed on the server's PATH and verified with uv --version before running npm install. It manages the isolated Python environment and dependencies; clients do not need it. On macOS with Homebrew, use brew 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) or systemctl --user (Linux). No sudo is 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 is 7850.
  • --bind ADDRESS — address to listen on. Default 0.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.

  • --port pins 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, claude or codex (claude)
  • CLAUDE_BIN / CODEX_BIN — executable name or path (claude / codex)
  • AGENTSDOCK_CLAUDE_TRANSPORT — interactive Claude transport: auto, agent-sdk, or print (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 for claude 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; 0 disables (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 — claude or codex (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/current points 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.

AgentsDock

An IDE designed for agentic AI research.© 2026 AgentsDock

Docs Support Report an issue Privacy Discord ↗