Docs

Setup guide

Last updated: September 21, 2026 · about 15 minutes

AgentsServer runs the real work on a remote machine you own.
AgentsDock clients run on your devices and connect to that server. Set up the remote once, then connect as many devices as you like.

Before you start

A remote machine you control — a macOS or Linux computer that stays on — to run the server. tmux is optional, only needed for the in-app terminal.
A Tailscale account (optional) — only needed to reach the remote from outside its local network. On the same Wi‑Fi you can use the machine's local IP address; Tailscale is what lets you connect securely from anywhere else.
Any provider CLI you plan to use — Claude Code, Codex, OpenCode, or Cursor — installed on the remote.
A device that can run an AgentsDock client: macOS, Windows, Linux, iPhone, iPad, or Android.

AgentsDock is fully self-hosted. Your chats, files, and API keys stay on your remote machine — the app is just a window into it.

Part 1Set up the remote

Do this once, on the machine that will do the work. It stays running and your devices connect to it.

1Install the AgentsServer

Clone the server and run its installer on the remote:

git clone https://github.com/ZhengyiLuo/AgentsServer.git
cd AgentsServer
./install.sh

The server listens on port 7850 by default and stays running on the remote — that's the piece your devices connect to.

It's secured with an access token that the installer prints once when it finishes — copy it now; you'll enter it on each device in Part 2. To show it again later, run this on the remote:

./install.sh --show-token

Every server command — update, restart, logs, uninstall — is on Manage your server.

View the AgentsServer repository on GitHub

2Sign in to provider CLIs on the remote

Install and sign in to whichever provider CLIs you want AgentsDock to use on the remote: Claude Code, Codex, OpenCode, or Cursor. Use that provider's normal login flow, such as browser sign-in or API-key configuration. For custom endpoints, see Connect agents.

3Install Tailscale on the remote optional

Only needed to reach the remote from outside its local network. If your devices are on the same Wi‑Fi as the remote, you can skip this and use the machine's local IP address in Part 2.

Install Tailscale on the remote machine and sign in. This gives the machine a private 100.x.x.x address that your other devices can reach from anywhere — without opening any ports to the public internet. Note that address (or the machine's Tailscale hostname); you'll enter it in Part 2.

More than one machine? Repeat Part 1 on each of them. AgentsDock can hold several servers at once — they all show up in the server menu at the top of the sidebar, and you switch between them with one click.

The server menu at the top of the AgentsDock sidebar listing three servers, with Add Server and Server Settings below — The server menu lists every server you've added. A green dot means it's reachable.

Part 2Connect from your device

Repeat this on any device you want to use as an AgentsDock client.

1Download the AgentsDock client

Download the client for your platform — macOS, Windows, Linux, iPhone, iPad, or Android — and open it.

2Install Tailscale on the device optional

Only needed if you installed Tailscale on the remote. Install it on this device too and sign in with the same account, so both are on the same private network and the app can reach the server. On the same local network, skip this and use the remote's local IP.

3Connect to your server

In AgentsDock, add a server with the remote's address — its Tailscale 100.x.x.x address and port 7850 — then paste the access token from Part 1 into the Access token field. It looks something like this:

ad_tok_9f3b7c2e••••••••••••••••••••   (sample)

This token lives on your server machine — the remote you set up in Part 1, not the device you're connecting from. To get it again, run this on the remote:

./install.sh --show-token

Click Test connection to confirm the app can reach the server, then Add & switch. You're connected: start a chat, pick a provider, and point it at a working directory on your remote.

AgentsDock connection form on macOS with the Access token field, a Test connection button, and Add and switch — Paste your access token into the **Access token** field, then click **Test connection** to verify before you save.

AgentsDock Settings on macOS showing a connected Mac Mini server and a Runtimes & prerequisites panel with tmux and provider CLI status — Once connected, the app's Settings let you monitor the connection and check that tmux and your provider CLIs are ready on the server.

Connected to more than one machine? Add each one the same way — open the server menu at the top of the sidebar and choose Add Server. From then on you can switch between servers from that menu at any time.

Switch servers from the menu at the top of the sidebar — each server keeps its own chats.

Not connecting?

Confirm the server URL opens in a browser on the same device — if the browser can't reach it, the app can't either.
Check that Tailscale is active and signed in on both ends, and that you used the remote's 100.x.x.x Tailscale address (not a local IP that only works on the remote's own network).
Make sure the port (7850) is included and the access token matches exactly, with no extra spaces.

Still stuck? Head to Support or ask in our Discord.

Connected? Explore what AgentsDock can do in Key features →