Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Security

Anyone holding a panel token can read your sessions, answer their prompts, start and stop sessions in your projects and, with the channel, prompt them. They can also lock or suspend the machines that allow it (power.lock, power.suspend) and wake machines over the LAN. Treat a token like an SSH key and keep the hub on your LAN or VPN.

  1. Tokens
  2. Pairing a device
  3. What reaches the hub

1. Tokens

TokenHeld byChecked as
bootstraptokenFile on the hubcompared in constant time
deviceeach paired browserrandom, stored as SHA-256, revocable
collectoreach workstation (collectors)names the machine; only /collect, /sync/, /git/, the report upload and the attachment fetch take it
notification keyone prompt’s buttonsrandom, dies with the prompt
view linkone report’s frameHMAC-signed, an hour, key drawn at start (reports)
attachment linkone attached fileHMAC-signed, six hours, key drawn at start

Rotating tokenFile (and restarting the hub) signs out only the devices still on the bootstrap token.

2. Pairing a device

sudo -u ccdash ccdash url --hub --config /etc/ccdash/hub.toml --qr

or “Connect a phone” in Settings on a paired browser. Every link carries a token minted for that one device: good for an hour until the link is opened, then for as long as the device keeps it.

Settings › Devices lists them with their browser and last use; rename one with its pencil, or revoke it to sign it out at its next request and end its push notifications. A device still on the bootstrap token sees “shared token” there and can take one of its own.

3. What reaches the hub

  • The API under /api/v1 needs a bearer token for everything.
  • /act/<key>/<action> takes a notification button’s one-time key; the access token never goes into a notification.
  • /collect and /sync/ take a collector’s token; /sync/ paths are checked to stay inside the synced directories.
  • /reports/-/upload takes a collector’s token; /reports/-/view/<key> takes a signed view link and serves the report as a sandboxed, opaque origin that loads nothing from the network, so a report’s scripts never see the panel’s token (reports).
  • /attachments/-/fetch/<id> takes a collector’s token; /attachments/-/view/<key> takes a signed link and serves the file with its kind read from its bytes, nosniff and a sandboxing policy: pictures, recordings and PDFs show in place, everything else is a download, so an uploaded page or SVG never runs in the panel’s origin. File names are reduced to letters, digits, ., _ and - before they reach a disk or a prompt. On a workstation the fetched files are the owner’s alone (0600 under a 0700 directory).
  • The OpenTelemetry receiver on a workstation takes no token, so the collector binds it to loopback only.
  • Lock and suspend reach only a machine whose collector has power.lock or power.suspend on; the collector checks that again itself. Magic packets go only to the broadcast address of a network the hub is on, or to a wake.via address in the hub’s own configuration (machines).
  • Nothing leaves the hub except Web Push to subscribed devices, encrypted for the device: the push service sees only ciphertext.
  • The hub keeps the synced ~/.claude as plain files: put its directory in an encrypted backup (state sync).