Docs

Manage your server

AgentsServer is the open-source backend that runs on your own machine. Everything below is done from a terminal on that machine — the server, not the device running the app.

AgentsServer on GitHub

Looking for every installer option, environment variable, multiple servers on one machine, or backups? See the Server reference.

No sudo is ever needed. The installer runs as your user, keeps the previous healthy release for rollback, and preserves your chat history, jobs, files, and access token across every update.

Install & update

First install — clone the repo and run the installer:

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

To update, pull and rerun the same installer. It swaps in the new runtime, restarts the service, and keeps your token and state:

git pull --ff-only
./install.sh

You can also update from the app — Settings → Install or update AgentsServer, or the Stable / Beta switch described in Updates.

Installer options

--port PORT — pin an exact port (default 7850). Without it, the installer picks one of the next 5 free ports if the default is taken.
--bind ADDRESS — bind address (default 0.0.0.0, reachable from your other devices).
--allow-port-fallback / --no-port-fallback — allow or forbid the nearby-port fallback.
--release-version VERSION — install a specific release.
--non-interactive — no prompts; for scripted or SSH-driven runs.
--show-token — print the access token and exit (see below).

Requirements: macOS (Apple silicon) or Linux, a preinstalled uv (brew install uv on macOS), and whichever provider CLIs you plan to use installed and signed in. tmux is optional — it powers the in-app terminal and managed updates.

Show your access token

The installer prints the token once when it finishes. To see it again at any time, run this on the server — it only reads the existing configuration and changes nothing:

./install.sh --show-token

Paste it into the app's Access token field when adding the server (see the Setup guide).

Check it's running

From the server machine:

curl http://127.0.0.1:7850/api/health

If the server requires a token (the default after install.sh), pass it as a bearer header:

curl -H 'Authorization: Bearer YOUR_TOKEN' http://127.0.0.1:7850/api/health

The response includes whether tmux and your provider CLIs are available. Inside the app, Settings shows the same runtime checks and a Restart server button.

Start, stop, restart, and logs

The installer registers AgentsServer as a user-level service that starts at login. Manage it with your platform's service manager.

macOS — the LaunchAgent is com.agentsdock.server:

# status
launchctl print gui/$(id -u)/com.agentsdock.server

# restart
launchctl kickstart -k gui/$(id -u)/com.agentsdock.server

# stop until next login / start again
launchctl bootout gui/$(id -u)/com.agentsdock.server
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentsdock.server.plist

# logs
tail -f ~/Library/Logs/AgentsServer/server.log
tail -f ~/Library/Logs/AgentsServer/server-error.log

Linux — the unit is agents-server.service:

# status
systemctl --user status agents-server.service --no-pager -l

# restart / stop / start
systemctl --user restart agents-server.service
systemctl --user stop agents-server.service
systemctl --user start agents-server.service

# logs
journalctl --user -u agents-server.service -f

Run it manually

For development or a one-off run without the service, start the server directly from the repo:

uv venv && uv sync --frozen
uv run python agent_server.py serve --bind 0.0.0.0 --port 7850

Set AGENTSDOCK_AGENT_TOKEN in that shell to require a token, and AGENTSDOCK_STATE_DIR to keep state somewhere other than ~/.agentsdock.

Uninstall

./uninstall.sh

This stops and removes the service, the versioned runtime, and the generated configuration including the access token. It asks before changing anything (--yes skips the prompt). Your chats, jobs, files, and terminals under ~/.agentsdock are kept, so a later ./install.sh picks them straight back up.

To delete that state as well, add --purge-state — it always requires typing the exact path to confirm and cannot be undone. Persistent chat terminals are left running as tmux sessions on this server's tmux server; tmux ls lists them. Only close sessions you recognise as this server's chat terminals — other tmux sessions on the machine, and any named server instances (which use their own tmux sockets), are unaffected by uninstalling the default server.

Settings & file locations

Where things live on the server:

~/.agentsdock — chat history, jobs, files, tokens (the state directory).
~/.local/share/agents-server — versioned server releases; current points at the active one.
~/Library/Logs/AgentsServer/ (macOS) or journalctl --user (Linux) — logs.

Most settings are environment variables. The ones you're most likely to touch:

AGENTSDOCK_AGENT_PORT / AGENTSDOCK_AGENT_BIND — port (7850) and bind address (0.0.0.0).
AGENTSDOCK_AGENT_TOKEN — the shared access token.
AGENTSDOCK_STATE_DIR — state directory (~/.agentsdock).
AGENTSDOCK_AGENT_CWD — default working directory for new chats (your home).
AGENTSDOCK_BACKEND — default backend, claude or codex.
CLAUDE_BIN / CODEX_BIN — path to each CLI if it isn't on PATH.

The full list, including job concurrency and memory guardrails, is in the README's configuration table.

Keep it private. Don't expose port 7850 to the public internet. Reach the server over Tailscale or another private network, and leave the access token enabled.