Skip to main content

Port Forwarding

Port forwarding in VibeControls lets you expose a port running on a remote machine (through a connected agent) so that you — or someone you share it with — can reach that service from a browser, without setting up VPN or SSH tunnels manually.

Common uses:

  • Preview a web app running on a remote dev server
  • Access a local API endpoint from your browser
  • Share a live demo of a work-in-progress with a colleague
  • Connect a local GUI tool to a database running on a remote machine

How It Works​

When you create a port forward, VibeControls routes traffic from a generated tunnel URL through the connected agent to the specified port on the target machine. The agent handles the tunneling, and VibeControls provides a stable URL you can bookmark or share.

Prerequisites​

  • At least one agent online and connected
  • The agent must have access to the machine (target) where the service is running
  • The target must be registered in VibeControls (see Targets)

Creating a Port Forward​

From the Tunnels Page​

  1. Navigate to Tunnels in the VibeControls sidebar
  2. Click New Port Forward (or New Tunnel)
  3. Fill in:
  • Name — a human-readable label (e.g. "dev-server-3000")
  • Agent — which agent will handle the tunneling
  • Target — the machine where the service is running
  • Target port — the port on the target machine to expose (e.g. 3000, 5432, 8080)
  • Description (optional)
  1. Click Create

VibeControls generates a tunnel URL immediately.

From an Agent's Detail Page​

  1. Open the agent detail page
  2. Click the Tunnels tab
  3. Click New Port Forward
  4. The agent is pre-selected — fill in the remaining fields
  5. Click Create

Tunnel URLs​

After creating a port forward, you will see the tunnel URL on the detail page:

https://<identifier>.tunnel.vibecontrols.com

This URL routes to the target port through the agent. You can:

  • Open it in your browser to access a web interface
  • Use it as an API base URL in your local tools
  • Share it with a colleague (subject to access settings)

Tunnel URLs remain active as long as:

  • The agent is online
  • The port forward is in an active state
  • The session has not been paused or deleted

Accessing Forwarded Ports​

Simply open the tunnel URL in a browser. If the service at the target port serves HTTP, you will see it rendered in the browser. If it serves a non-HTTP protocol, you can use the URL as an endpoint in compatible tools.

For example, if you are forwarding a PostgreSQL port, you would use the tunnel URL as the host in your database GUI.

Managing Port Forwards​

Navigate to Tunnels in the sidebar to see all port forwards in your workspace.

The list shows:

  • Name and description
  • Agent and Target it connects through
  • Target port
  • Status — Active, Paused, or Error
  • Created by and creation date
  • Tunnel URL (click to copy)

Pausing a Port Forward​

To temporarily disable a tunnel without deleting it:

  1. Open the port forward detail page
  2. Click Pause

The tunnel URL will return a 503 until you resume it. Click Resume to reactivate.

Deleting a Port Forward​

  1. Open the port forward detail page
  2. Click ... → Delete
  3. Confirm the deletion

The tunnel URL immediately stops working.

Port Forward Status​

The detail page shows a live status indicator:

  • Active — traffic is flowing normally
  • Paused — manually paused by a user
  • Agent offline — the agent is not reachable; the tunnel is unavailable until the agent reconnects
  • Error — connection to the target port failed (service may be down, or the port may be wrong)

If a tunnel shows as Error, check:

  • The service is actually running on the target port
  • The target machine is reachable from the agent
  • The port number is correct

Sharing Port Forwards​

Tunnel URLs are workspace-private by default. To share a tunnel URL with someone outside your workspace, or to give a teammate access without requiring them to log in, you can generate a public access token for the tunnel.

  1. Open the port forward detail page
  2. Click Share
  3. Toggle Public access on
  4. Optionally set an expiry
  5. Copy the shareable URL

The public URL includes an access token that grants temporary access to the tunnel. Anyone with this URL can reach the forwarded port until the token expires or is revoked.

To revoke public access, toggle Public access off on the tunnel detail page.

Tips​

  • Use descriptive names for port forwards so you can remember which service each one points to: "staging-api-8080", "local-redis-6379".
  • Set an expiry on public-access tunnel URLs when sharing for demos — it ensures the link stops working once the demo is over.
  • If you frequently forward the same port for a project, note the tunnel URL in the vibe's notes so anyone working on that project can find it quickly.
  • Port forwards persist across agent restarts as long as the agent comes back online — you do not need to recreate them.