Setup guide

Quick setup guide

Last updated: July 20, 2026 · about 15 minutes

AgentsDock has two halves. The AgentsServer runs the real work on a remote machine you own; the app on your Mac, iPhone, or iPad is your window into it. 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 — with tmux installed. This runs the server.
A Tailscale account, so your devices can reach the remote securely from anywhere.
Your Claude Code and/or Codex accounts, to sign the CLIs in on the remote.
A Mac, iPhone, or iPad to run the app.

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 authorized with an access token; keep that token handy for Part 2.

View the AgentsServer repository on GitHub

2Sign in to Claude Code and Codex on the remote

AgentsDock runs the Claude Code and Codex CLIs on the remote, using your own accounts — it never proxies or sees your model requests. So the CLIs must be installed and signed in on the remote machine, not on your phone or laptop. Run each CLI you plan to use once and complete its sign-in. If a CLI isn't signed in, AgentsDock shows that backend as unavailable.

3Install Tailscale on the remote

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 — without opening any ports to the public internet. Note that address (or the machine's Tailscale hostname); you'll enter it in Part 2.

Part 2Connect from your device

Repeat this on any Mac, iPhone, or iPad you want to use.

1Download AgentsDock

Get the app for macOS, iPhone, or iPad — the platforms available today — and open it.

2Install Tailscale on the device

Install Tailscale on this device too and sign in with the same account you used on the remote. That's what puts them on the same private network so the app can reach the server.

3Connect to your server

In AgentsDock, add a server with the remote's address — its Tailscale 100.x.x.x address and port 7850 — and the access token from Part 1. Save it, and you're connected: start a chat, pick Claude Code or Codex, and point it at a working directory on your remote.

AgentsDock Settings on macOS showing a connected Mac Mini server and a Runtimes & prerequisites panel with tmux, Claude Code, and Codex status — From the app's Settings, you can see and monitor the connection to your remote — and check that tmux, Claude Code, and Codex are ready on the server.

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.