CANBAN

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 canband hosts keep running agents, collecting reports, executing FIFO Queue Merge, and polling linked GitHub repositories.
  • Unified Board & Notifications: Canban.app merges local and remote Projects into one HostRegistry, routing operations by owning host_id and surfacing remote Needs you / Updates items 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 in Offline · Cached read-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:

sh
curl -fsSL https://canban.dev/install.sh | bash -s -- --headless
canban service install --tailscale --port 7680
canban service status

canban 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 --tailscale binds the host's Tailscale IPv4 (100.64.0.0/10, default port 7680) and persists settings in <home>/config/server.json. A 256-bit Bearer secret is stored in <home>/server.token (0600). Pre-auth host.probe exposes only non-sensitive identity (server_id, hostname, platform, version, api_version), while all RPCs and herdr.connect PTY streams authenticate against server.token.
  • Pairing URI: Run canban pair [--port 7680] on the remote host to print a copyable canban://<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.app manages a background ssh -L Unix-socket forwarder into a mode-0600 local 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_API compatibility, systemd --user / launchd state, and SQLite DB/WAL sizes.
  • Herdr & Toolchain: Resolved hc binary, Core ID, active PTY count, git, python3, tailscale, and resolved paths for enabled Agent profiles.
  • Live Logs & Updates: Stream server.log and updater.log, or trigger a remote update.daemon directly from the UI when ApiMismatch is detected.