Tunnels
A tunnel exposes a localhost port on your target machine to the public internet via an outbound connection — useful for sharing a dev server, exposing a webhook receiver, or pair-programming over a browser terminal.
What you'll learn
- The two built-in tunnel providers
- How to create a tunnel
- The control-plane tunnel that the agent itself uses
Two providers
| Provider | Plugin | URL format | Setup |
|---|---|---|---|
| Cloudflare quick tunnels | @vibecontrols/vibe-plugin-tunnel-cloudflare | https://<random-words>.trycloudflare.com | None — uses Cloudflare's free quick-tunnel infrastructure |
| VibeTunnels (frp-based) | @vibecontrols/vibe-plugin-tunnel-vibetunnels | Custom (depends on your frp server) | Requires you to run your own frps |
Plugins implement the TunnelProvider interface from @vibecontrols/plugin-sdk. The agent's tunnel registry picks the appropriate provider when you create a tunnel.
How quick tunnels work (Cloudflare)
The plugin spawns cloudflared tunnel --url <local-port> as a child process, parses the resulting *.trycloudflare.com URL from stderr, and persists tunnel state to ~/.boff/vibecontrols/agents/<agentId>/tunnel.state.json. Each tunnel has a unique unguessable subdomain.
How frp tunnels work (VibeTunnels)
The plugin spawns frpc against a configured frps server. Useful when:
- Your network blocks outbound Cloudflare connections
- You need a stable hostname on your own domain
- You prefer self-hosted infrastructure
You configure the frps server URL + auth via plugin configuration.
The agent's own control-plane tunnel
The agent ALSO needs a tunnel for the platform to reach it (since the agent runs behind your firewall). The Cloudflare plugin handles this too — the agent's control-plane tunnel URL is stored as Agent.tunnelUrl in the backend database. This is automatic on first run; you don't manage it directly.
User vs admin
- User: create a tunnel for a port → see Port Forwarding & Tunnels.
- Admin: pick which tunnel providers to allow + configure VibeTunnels if used → see Tunneling & networking.