| name | relay-add-device |
| description | Add a new client device to the relay using ADDITIVE TRUST (no CA regeneration, no impact to existing devices): mint the device a client cert with a fresh CN from the shared CLIENT CA (which the VPS already trusts), add --allow-cn for the new CN, restart ghostunnel, fill the device's client bundle, and re-baseline the health check. Use when the user wants to authorize a new laptop/PC/device to use the relay, or "add a client". |
| allowed-tools | Read, Edit, Write, Bash, Agent, AskUserQuestion, TodoWrite |
Add a client device (additive trust)
Read CLAUDE.md and docs/GETTING-STARTED.md first. The relay is client-IP-agnostic (auth = mTLS cert +
CDN service token; upstreams only ever see the VPS static IP), so the new device's network adds no ban
risk. Additive trust = each device gets its own CN (signed by the shared client CA the VPS
already trusts) — so it can be revoked alone and the server cert is never re-keyed (existing devices
stay up). Prefer this over full CA regeneration (which breaks everyone). Pick the next free CN
(e.g. zt-relay-client-<N>).
Drive it with a TodoWrite list.
Steps
- On the box holding the client CA (
certs/out/client-ca.{key,crt}): mint a client cert with the
fresh CN: MSYS_NO_PATHCONV=1 bash certs/gen-client-cert.sh zt-relay-client-<N> <outdir>. This also
drops server-ca.crt into the bundle (so the device can verify the server). The client CA key never
leaves this box.
- On the VPS (delegate to the
relay-operator agent over your secure SSH path — back up first):
- Back up the ghostunnel unit (
*.bak.<ts>).
- Add
--allow-cn zt-relay-client-<N> to the ghostunnel server unit. No client-ca.crt change —
the VPS already trusts the shared client CA that signed the new cert.
sudo systemctl daemon-reload && sudo systemctl restart ghostunnel-server; confirm active.
- Fill the device bundle: copy
local/win-client-template/ → the device's own bundle, drop in
server-ca.crt, this device's client.{crt,key}, and the .env secrets (CDN service-token
id/secret, the relay hostname, the gateway API key). Run setup.ps1, then test the relay client.
- Re-baseline the health check — a new
--allow-cn is otherwise flagged as drift on the next run:
bash local/healthcheck-pull.sh --update-baseline.
Verify
- The new device gets a real completion through the relay.
- Existing devices still work (additive path never touched the server cert).
- Next health pull is clean (no unexpected
--allow-cn drift).
Guardrails
- Never regenerate the CA to add a device (that re-keys the relay and breaks every device) unless the
user explicitly wants the full rotation.
- Never commit or print the device key /
.env. Never weaken loopback/TCP-mode/two-gate invariants.
- Each device keeps its own CN — never reuse one CN across machines (can't revoke one alone).
