Skip to main content

Port Forwarding & Tunnels

Expose any port from the agent's machine to the public internet. See the concept.

What you'll learn​

  • Create a tunnel for a port
  • Pick your tunnel provider
  • Manage tunnel lifecycle

Create a tunnel​

vibecontrols tunnels create \
  --agent <agent-id> \
  --port 3000 \
  --provider cloudflare

The agent's tunnel plugin spawns the appropriate subprocess (cloudflared or frpc) and returns the public URL.

Providers​

ProviderPluginURL
cloudflare@vibecontrols/vibe-plugin-tunnel-cloudflarehttps://<random-words>.trycloudflare.com
vibetunnels@vibecontrols/vibe-plugin-tunnel-vibetunnelsDepends on your frps config

The default provider is configured per-agent. Both are pluggable — add custom providers via the plugin SDK.

List tunnels​

vibecontrols tunnels list                    # current workspace
vibecontrols tunnels list --agent <agent-id>

Or hit the agent's REST API directly:

curl -H "x-agent-api-key: $KEY" http://localhost:3005/api/profiles/default/tunnel

Tear down​

vibecontrols tunnels delete <tunnel-id>

The plugin terminates the subprocess and removes the tunnel record.

Per-port forwards​

For local-to-remote, remote-to-local, or dynamic SOCKS forwards (not public tunnels), use vibecontrols port-forward commands. These are tied to SSH targets.

Agent's own control-plane tunnel​

The agent itself uses a tunnel for the backend to reach it. This is set up automatically on vibe start. Its URL is stored at Agent.tunnelUrl on the backend. You don't manage it directly — it's part of the agent lifecycle.

Next steps​