CANBAN // DOCS // REMOTE HOSTS
Remote Linux Hosts, Tailscale & SSH
A single Canban.app desktop client connects simultaneously to your local Mac (This Mac) and one or more remote Linux or macOS canband hosts over Tailscale TCP or SSH.
Simultaneous multi-host & offline-resilient execution
Each host runs a self-contained canband + local herdr-core (hc) pair owning its own SQLite WAL database, Projects, Cards, Workflows, Scheduler, and Git worktrees:
- 24/7 Autonomous Progression: When your laptop sleeps or goes offline, remote
canbandhosts keep running agents, collecting reports, executing FIFO Queue Merge, and polling linked GitHub repositories. - Unified Board & Notifications:
Canban.appmerges local and remote Projects into oneHostRegistry, routing operations by owninghost_idand surfacing remoteNeeds you/Updatesitems in⌘I. - Offline Snapshot Cache: Successful remote snapshots are cached under
<local-home>/cache/hosts/<host_id>.json. If Tailscale disconnects, remote boards remain inspectable inOffline · Cachedread-only mode.
Installing headless Linux canband
On headless Linux (x86_64 or aarch64) servers without a desktop session, install standalone canban (no GTK4 or GStreamer required) and register a persistent systemd --user service:
curl -fsSL https://canban.dev/install.sh | bash -s -- --headless
canban service install --tailscale --port 7680
canban service statuscanban service install enables loginctl enable-linger when available so user services and active herdr-core PTYs persist across logouts.
Tailscale direct TCP vs. SSH pairing
Canban uses a Tailscale-first direct data plane with SSH bootstrap and fallback:
- Tailscale Direct TCP (Recommended):
canban serve --tailscalebinds the host's Tailscale IPv4 (100.64.0.0/10, default port7680) and persists settings in<home>/config/server.json. A 256-bit Bearer secret is stored in<home>/server.token(0600). Pre-authhost.probeexposes only non-sensitive identity (server_id,hostname,platform,version,api_version), while all RPCs andherdr.connectPTY streams authenticate againstserver.token. - Pairing URI: Run
canban pair [--port 7680]on the remote host to print a copyablecanban://<addr>:<port>#<token>URI, or use the desktop Connect a Machine wizard to discover Tailscale peers (tailscale status --json) and auto-pair or bootstrap over SSH. - Managed SSH Tunnel Fallback: For pure-SSH hosts without Tailscale,
Canban.appmanages a backgroundssh -LUnix-socket forwarder into a mode-0600local socket directory.
Built-in Diagnostics & remote daemon upgrades
Open Settings → Diagnostics to verify and repair local or remote hosts end to end:
- Transport & Latency: Socket, Tailscale TCP, or SSH tunnel state, RTT (
ms), and reconnect history. - Canban Service & Storage: Daemon PID, platform, version,
DESKTOP_APIcompatibility,systemd --user/launchdstate, and SQLite DB/WAL sizes. - Herdr & Toolchain: Resolved
hcbinary, Core ID, active PTY count,git,python3,tailscale, and resolved paths for enabled Agent profiles. - Live Logs & Updates: Stream
server.logandupdater.log, or trigger a remoteupdate.daemondirectly from the UI whenApiMismatchis detected.