Tunnel

Wirebox tunnels provide secure reverse proxy connections that expose your agent’s local services (FastAPI webhooks, local agent APIs, development servers) to the public internet. With tunnels, your local development workstation or firewalled private environment can receive external webhook notifications and HTTP traffic without opening firewall ports, configuring static IPs, or setting up complex dynamic DNS.

How It Works

Outbound Edge Session: The Wirebox CLI or client initiates an outbound TLS connection to Wirebox’s edge routing network.
Public Edge URL: Wirebox assigns a public HTTPS subdomain (e.g. https://eva.wirebox.run).
Transparent HTTP & WebSocket Proxying: Incoming HTTP requests and WebSocket upgrades (Upgrade: websocket) to the public URL are forwarded locally to your configured loopback port or in-memory handlers, with full support for request headers, binary payloads, subprotocol negotiation (Sec-WebSocket-Protocol), and bidirectional streaming.

Starting a Tunnel via CLI

The simplest way to start a tunnel is using the Wirebox CLI:

CLI

# Expose local port 3000 to public edge
wirebox tunnel connect eva --port 3000

# Expose local port 8000 for agent @sales-bot
wirebox tunnel connect sales-bot --port 8000

Output:

Connecting tunnel for 'eva' to http://localhost:3000...
[Status] Connected to Wirebox Edge

========================================================
  Wirebox Tunnel Online
  Agent Handle:  @eva
  Public URL:    https://eva.wirebox.run
  Local Target:  http://localhost:3000
========================================================

Press Ctrl+C to disconnect.

Connecting local services to external agentsTunnels allow autonomous agents or external webhook senders to communicate with local development servers, test runners, or private APIs without port forwarding or static public IPs.

Programmatic Tunnel Management

Both the Python and TypeScript SDKs allow inspecting active tunnel sessions, health statuses, and routing targets:

from wirebox import Wirebox

with Wirebox() as wb:
    # 1. List active tunnels
    tunnels = wb.tunnels.list()
    for tun in tunnels:
        print(f"[{tun.status}] {tun.public_url} -> {tun.target_url}")

    # 2. Get tunnel details
    tun = wb.tunnels.get("tun_01J8DEF456GHI789")
    print("Connected clients:", tun.connected_clients)

    # 3. Update administrative status ('active' | 'disabled')
    updated = wb.tunnels.update("tun_01J8DEF456GHI789", status="active")
    print("Updated status:", updated.status)

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

// 1. List active tunnels
const { tunnels } = await wb.tunnels.list();
for (const tun of tunnels) {
  console.log(`[${tun.status}] ${tun.publicUrl} -> ${tun.targetUrl}`);
}

// 2. Get tunnel details
const tun = await wb.tunnels.get("tun_01J8DEF456GHI789");
console.log("Connected clients:", tun.connected_clients);

// 3. Update administrative status ('active' | 'disabled')
const updated = await wb.tunnels.update("tun_01J8DEF456GHI789", {
  status: "active",
});
console.log("Updated status:", updated.status);

# List active tunnels
wirebox tunnel list

# Update status
wirebox tunnel update eva --status disabled

WebSocket Support

Wirebox tunnels support bidirectional WebSocket proxying out of the box:

Local Port / URL Forwarding: Any WebSocket upgrade request to https://{handle}.wirebox.run is transparently upgraded and proxied to your local server (e.g. ws://127.0.0.1:8000).
Subprotocol Negotiation: Automatically preserves and echoes back Sec-WebSocket-Protocol headers (e.g. for Vite HMR, chat protocols, or custom agent streaming).
In-Memory WebSocket Handlers: TypeScript SDK allows handling incoming WebSocket connections in-process without listening on a TCP port.

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox({ apiKey: process.env.WIREBOX_API_KEY });

const session = await wb.tunnels.connect("eva", {
  wsHandler: async (ws) => {
    console.log(`WebSocket client connected at path: ${ws.path}`);

    ws.on("message", (data, isBinary) => {
      console.log("Received:", data);
      ws.send(`Echo: ${data}`);
    });

    ws.on("close", (code, reason) => {
      console.log(`Client disconnected: ${code} ${reason}`);
    });
  },
});

import asyncio
from wirebox import AsyncWirebox

async def main():
    async with AsyncWirebox() as wb:
        # Automatically proxies both HTTP requests and WebSocket upgrades to port 8000
        session = await wb.tunnels.connect("eva", forward_to=8000)
        print(f"Tunnel live at {session.public_url}")
        await session.wait_closed()

asyncio.run(main())

# Expose local port 8000 (proxies both HTTP and WebSocket traffic)
wirebox tunnel connect eva --port 8000

Local Webhook Testing Workflow

A common workflow for autonomous agents is developing and debugging webhook handlers locally:

Start your local webhook receiver on port 3000:
uvicorn agent:app --port 3000
Start a Wirebox tunnel for your agent:
wirebox tunnel connect eva --port 3000

wirebox webhook create \
  --url https://eva.wirebox.run/api/webhooks \
  --events email.received \
  --agent eva

Send an email to eva@wireboxmail.com. The webhook event lands directly on your local localhost:3000 server for interactive step debugging.

Get Started

Capabilities

Integrations

How It Works

Starting a Tunnel via CLI

Programmatic Tunnel Management

WebSocket Support

Local Webhook Testing Workflow

​How It Works

​Starting a Tunnel via CLI

​Programmatic Tunnel Management

​WebSocket Support

​Local Webhook Testing Workflow

​Related APIs

How It Works

Starting a Tunnel via CLI

Programmatic Tunnel Management

WebSocket Support

Local Webhook Testing Workflow

Related APIs