Troubleshooting

Agent won't start

vibe status                   # what's the agent doing?
vibe health                   # HTTP probe

Common issues:

Port 3005 in use — agent auto-picks the next free port, but if it can't, set PORT=<n> env var
tmux/ttyd/cloudflared missing — run vibe setup to auto-install system deps
Permission errors on ~/.boff/vibecontrols/ — chmod -R u+rw ~/.boff/vibecontrols

The agent is running but the backend can't see it.

vibe status — is the tunnel up?
Check the agent's outbound tunnel URL: curl -H "x-agent-api-key: $KEY" http://localhost:3005/api/agent/tunnel
Try vibe restart (or kill + vibe start)
Re-push gateway credentials from the web app: Targets → <target> → Re-authenticate

The agent stored a stale OAuth credential. The agent should self-heal — but if not:

vibe restart

If still failing, re-push gateway auth from the web app.

vibecontrols sessions describe <session-id>

Look at the status and lastOutput fields. Common causes:

workingDirectory doesn't exist on the agent's machine
command not found on PATH
Session-type plugin not loaded (e.g., wezterm session but wezterm not installed)

Is the underlying service actually listening on the port? vibecontrols sessions create --type TERMINAL → curl localhost:3000 on the agent
vibecontrols tunnels list — is the tunnel still active?
For Cloudflare quick tunnels: trycloudflare.com has rate limits; spin up a new tunnel
For VibeTunnels: check your frps is up

vibecontrols auth status
vibecontrols auth login          # re-auth if token expired
vibecontrols workspace set <id>  # if you switched workspaces

Usually a backend/DB schema drift after an upgrade. Wait a few minutes (migrations may still be running) or contact support.

vibe autostart uninstall
rm -rf ~/.boff/vibecontrols
npm uninstall -g @vibecontrols/agent @vibecontrols/cli

Then re-install fresh.