Gueridon

Prerequisites

Before starting, ensure the target machine has:

1. Debian 12+ (or similar Linux with systemd) — tested on Debian 13 trixie
2. Node.js >= 20 — Debian 13 ships this in its repos (sudo apt-get install nodejs npm)
3. npm — installed alongside Node
4. Tailscale — joined to your tailnet, with HTTPS cert provisioning enabled
5. Claude Code CLI — installed via curl -fsSL https://claude.ai/install.sh | bash, authenticated via claude auth
6. A MAX subscription — CC process spawns require it

Setup Workflow

Follow these steps in order on the target server.

Step 1: Install Node.js and Claude Code

# Node (Debian 13)
sudo apt-get update && sudo apt-get install -y nodejs npm

# Claude Code
curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude auth   # interactive — follow the browser OAuth flow

Step 2: Configure Claude Code for bridge use

The bridge spawns CC as a child process. Disable interactive terminal features that would pollute the stdio event stream.

Merge into ~/.claude.json:

"autoCompactEnabled": false,
"verbose": false,
"autoConnectIde": false,
"fileCheckpointingEnabled": false,
"respectGitignore": false,
"claudeInChromeDefaultEnabled": false

Create ~/.claude/settings.local.json:

{
  "spinnerTipsEnabled": false,
  "prefersReducedMotion": true
}

Remove default marketplace plugins (adds startup overhead the bridge doesn't use):

rm -rf ~/.claude/plugins

Step 3: Clone and install

mkdir -p ~/Repos
git clone https://github.com/spm1001/gueridon.git ~/Repos/gueridon
cd ~/Repos/gueridon
npm install

Smoke test — bridge should start and complain only about missing VAPID keys:

npx tsx server/bridge.ts
# Expected: "[push] No VAPID keys ... push disabled"
#           "[bridge] listening on port 3001"
# Ctrl+C to stop

Step 4: Generate VAPID keys for push notifications

Push notifications require a VAPID keypair. The bridge reads from ~/.config/gueridon/vapid.json.

mkdir -p ~/.config/gueridon
cd ~/Repos/gueridon
node -e "
  const wp = require('web-push');
  const keys = wp.generateVAPIDKeys();
  require('fs').writeFileSync(
    require('os').homedir() + '/.config/gueridon/vapid.json',
    JSON.stringify(keys, null, 2)
  );
  console.log('VAPID keys written to ~/.config/gueridon/vapid.json');
"

Run this from within the gueridon directory — web-push is a project dependency resolved via node_modules/.

Step 5: Configure Tailscale HTTPS

sudo tailscale serve --bg --https=443 http://localhost:3001
sudo tailscale serve status
# Should show: https://<hostname>.<tailnet>.ts.net/ -> proxy http://localhost:3001

HTTPS is required for push notifications (Push API needs a secure context).

Step 6: Install systemd service

sudo cp ~/Repos/gueridon/gueridon.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now gueridon

The unit file runs tsx server/bridge.ts as the configured user with KillMode=process — bridge restart does NOT kill CC child processes. They become orphans; the new bridge reaps them on startup (SIGTERM) and the next client connection resumes via --resume.

Step 7: Verify from phone

1. Open https://<hostname>.<tailnet>.ts.net/ on your phone
2. Folder switcher should list project folders
3. Tap a folder, send a test prompt, verify response
4. Allow notifications when prompted
5. Send another prompt, lock phone — push notification should arrive when Claude finishes
6. iOS: Share -> Add to Home Screen for standalone PWA mode

Status Checks

Bridge health

sudo systemctl status gueridon        # active (running)?
journalctl -u gueridon -f             # tail live logs
curl -s http://localhost:3001/folders  # should return JSON array
curl -s http://localhost:3001/status   # debug: sessions, memory, recent events

Tailscale HTTPS

sudo tailscale serve status           # HTTPS proxy active?

Active sessions

The /status endpoint returns current sessions, including per-folder CC PIDs, session IDs, and turn state. Useful for diagnosing stuck or orphaned processes.

Session persistence file: ~/.config/gueridon/sse-sessions.json — tracks active CC PIDs so the bridge can reap orphans after restart.

Push notification state

• VAPID keys: ~/.config/gueridon/vapid.json
• Active subscriptions: ~/.config/gueridon/push-subscriptions.json

Troubleshooting

Port 3001 already in use

Another bridge instance or process is holding the port:

lsof -i :3001
# Kill the offending process, then restart
sudo systemctl restart gueridon

VAPID key regeneration

If push notifications stop working (expired subscriptions, key mismatch):

cd ~/Repos/gueridon
rm ~/.config/gueridon/vapid.json
rm ~/.config/gueridon/push-subscriptions.json
# Re-run the VAPID generation command from Step 4
sudo systemctl restart gueridon
# Re-subscribe from phone (notifications permission prompt will reappear)

TLS certificate issues

Tailscale serve handles cert provisioning and renewal automatically. If HTTPS stops working:

sudo tailscale serve status             # is the proxy still registered?
sudo tailscale serve --bg --https=443 http://localhost:3001  # re-register

If DNS resolution fails (only tailnet names resolve), check resolvectl status — the fix is upstream in Tailscale DNS settings or router DHCP, not per-machine.

Orphan CC processes

After a bridge crash, CC child processes may survive. The bridge reaps them automatically on startup by reading ~/.config/gueridon/sse-sessions.json and sending SIGTERM (escalating to SIGKILL after 3 seconds). Processes older than 24 hours are skipped.

To check manually:

ps aux | grep 'claude -p'

Bridge restart during active session (self-deployment)

When working on gueridon from gueridon, restarting the bridge kills the bridge, the new bridge reaps the CC process, and the client reconnects with --resume. Chain test and restart in a single Bash call:

npm test 2>&1 | tail -5 && sudo systemctl restart gueridon

Do NOT run test and restart as separate tool calls — the session resumes between them and the restart intent is lost.

Session Awareness

Gueridon-spawned CC sessions differ from direct terminal sessions:

The bridge sets --permission-mode default and loads MCP config from ~/.claude/settings.json via --mcp-config, so project-level settings and MCP servers work the same as terminal sessions.

Updating

cd ~/Repos/gueridon
git pull
npm install
sudo systemctl restart gueridon

After restart, the bridge reaps any orphan CC processes from the previous instance and clients reconnect automatically via SSE.

Key Paths