Running tclaude on a server¶
tclaude runs just as well on a headless box (a VM, a home server, a cloud instance) as on a laptop. The difference is only in who keeps it running and how you reach it.
tclaude does not install a login service for you. There is no
tclaude setup --install-service. How agentd starts is your call: a systemd
user unit, a system unit under a dedicated account, a launchd agent, a unit
your config management templates, or tclaude agentd serve in a tmux or
screen window you leave behind. The pages here show the common shapes so the
choice is easy:
- systemd: Linux user or system units, including cgroup delegation for per-agent resource limits.
- launchd: a macOS LaunchAgent.
- Ansible: a generic play that templates and enables the systemd user unit.
What has to keep running¶
| Process | What it is | Who starts it |
|---|---|---|
agentd |
The daemon: API, dashboard, scheduler, spawns. tclaude agentd serve, or the standalone tclaude-agentd serve (same code; keep tclaude on PATH beside it). |
You, via your supervisor. |
| The tclaude tmux server | tmux -L tclaude. Every agent pane lives in it. |
Whatever first creates a session, normally agentd on the first spawn. You can also run it as its own unit (see systemd). |
| The harness CLIs | claude, codex, opencode, copilot, gemini, pi. One per agent, inside its pane. |
agentd, through tclaude session new. They must be on the PATH that agentd and the tmux server see. |
agentd itself can stop and start without touching running agents. It picks
up the panes it finds on the tclaude tmux server. The tmux server is the part
whose death ends every agent. Agents whose panes died show as offline and come
back with Resume in the dashboard, or tclaude agent resume <agent>.
Paths that matter to a supervisor:
~/.tclaude/data/config.json: settings. Theagent.*keys mirror theagentd serveflags (--helpnames each one).~/.tclaude/data/: SQLite database and private daemon state.~/.tclaude/api/agentd-socket/agentd.sock: the socket agents and the CLI talk to.~/.tclaude/data/output.log: the daemon log, rotated byagentditself.$TMUX_TMPDIR/tmux-<uid>/tclaude(default/tmp/tmux-<uid>/tclaude): the tmux socket.
What a headless box changes¶
No tray, no browser. Pass --no-tray (or set agent.disable_tray).
agentd also skips the tray on its own when it can't reach one, but the flag
keeps the log quiet.
A stable port and a token you can find. With no terminal attached, the
startup banner does not print the operator token (--print-human-token
defaults to auto). Set a fixed port and persist the token so the CLI on the
server can authenticate as you:
--persist-operator-token writes a 0600 ~/.tclaude/data/operator_token that
the CLI reads automatically. The config-file forms are agent.dashboard_port
and agent.persist_operator_token. Do not use --print-human-token=always
under a supervisor. It writes the bearer token to the journal or log file.
Harness logins. Log each harness in once, as the user agentd runs as,
from an SSH shell on the server. Most offer a flow that does not need a local
browser. For example, Claude Code prints a URL and takes a pasted code (or
claude setup-token for a long-lived token), and Codex has
codex login --device-auth. Check each CLI's own help for the others. If
another tclaude instance is already logged in and federated
with this one, tclaude harness credentials push can copy credentials over.
Then confirm agentd can find the binaries:
Reaching the dashboard. The dashboard listens on loopback. Pick one way in:
-
SSH tunnel. Simplest, and nothing new is exposed. With the fixed port above:
ssh -L 7878:127.0.0.1:7878 you@server tclaude agent dashboard --print # run on the server, inside that SSH sessionOpen the printed
http://127.0.0.1:7878/?init_token=…URL in your local browser within about a minute. -
A private network such as Tailscale or WireGuard: bind the dashboard to that interface with
--dashboard-bind(oragent.dashboard_bind). Its only gate is a cookie plus the operator token, so do this only on a network you already trust. tclaude remote-access: tclaude's own mTLS + passphrase HTTPS listener, for a phone or anything outside your private network. See Operating remotely.
Linking machines. To have agents on this server talk to agents on another machine, link the instances through a hub. See Federation setup.
Then open the dashboard¶
Once agentd runs under your supervisor of choice, open the dashboard (over
your tunnel or network) and work from there. Spawning, attaching to panes in
the browser terminal, approvals, and logs all work the same as on a desktop.
See Dashboard.