# 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.
