Skip to main content

Health

Three independent health signals.

What you'll learn​

  • The three health levels
  • What each one means
  • How they're surfaced

Agent health​

The agent posts a heartbeat (POST /api/agent/heartbeat or similar) periodically. The backend updates Agent.lastHeartbeat and Agent.isActive accordingly.

Indicators:

  • Active — recent heartbeat (< ~30s)
  • Stale — heartbeat older than threshold
  • Disconnected — no heartbeat for an extended period

Also exposed via GET /health on the agent's local REST server (port 3005 by default).

Session health​

Each session has a status field on the backend (SessionStatus enum):

  • PENDING — created but not started
  • STARTING — provider is initializing
  • RUNNING — alive
  • STOPPED — clean exit
  • ERROR — provider error
  • TERMINATED — explicit terminate

The session provider (tmux, wezterm, zellij, ssh, etc.) implements a healthCheck() method that the agent polls.

Tunnel health​

The tunnel provider exposes a status field. For Cloudflare quick tunnels: the cloudflared subprocess is monitored; if it dies, status flips. For frp: similar process monitoring.

Surfaced where​

  • Web app: per-agent / per-vibe / per-session health badges
  • CLI: vibecontrols agents list --active, vibecontrols sessions list
  • REST: GET /health on agent
  • GraphQL subscriptions: live updates on agent/session/tunnel state changes

Next steps​