HTTP Tunnels
The tunnel command exposes your local server to the internet with a public URL. Traffic is tunneled through Hooklistener's servers to your local machine, similar to ngrok.
Basic usage
# Tunnel to localhost:3000 (default)
hooklistener tunnel
# Tunnel to a specific port
hooklistener tunnel --port 8080
# Tunnel to a specific host and port
hooklistener tunnel --host 127.0.0.1 --port 5000
# Use a persistent subdomain (paid plans)
hooklistener tunnel --slug my-cool-app
Options
| Flag | Short | Default | Description |
|---|---|---|---|
--port | -p | 3000 | Local port to forward to |
--host | — | localhost | Local host to forward to |
--org | -o | Config default | Organization ID |
--slug | -s | Random | Static tunnel slug (paid plans) |
How it works
- The CLI opens a WebSocket connection to Hooklistener's tunnel server
- You get a public URL (e.g.,
https://abc123.hooklistener.dev) - HTTP requests to that URL are forwarded through the WebSocket to your local server
- Your local server's response is sent back to the original caller
The tunnel supports:
- All HTTP methods
- Request headers and bodies
- Binary content (base64 encoded)
- Response headers and bodies
- 30-second per-request timeout
Interactive TUI
The tunnel command shows a live dashboard:
Display
- Tunnel URL — your public URL with a copy indicator
- Local target — where traffic is forwarded to
- Status — connected (static or ephemeral) with uptime
- Statistics — total requests, success rate, average response time
Request table
A live table of recent requests showing method, path, status code, and duration.
Keyboard shortcuts
| Key | Action |
|---|---|
↑ / ↓ / j / k | Scroll request list |
PageUp / PageDown | Page scroll |
Home / End | Jump to top/bottom |
c | Copy tunnel URL to clipboard |
r | Manually reconnect |
q / Esc | Quit |
Static tunnels
By default, tunnels get a random subdomain that changes each time. With a static tunnel slug, you get a persistent subdomain:
hooklistener tunnel --slug my-app
# Always available at https://my-app.hooklistener.dev
Static tunnels require a paid plan. See Static Tunnels for management commands.
Connection behavior
- Auto-reconnect — automatic reconnection with exponential backoff
- Heartbeat — 30-second ping interval
- Max retries — 10 attempts before giving up
- Backoff — starts at 1 second, maxes out at 60 seconds, with 30% jitter
Use cases
- Webhook development — receive webhooks from third-party services on your local machine
- Mobile app testing — connect a mobile app to your local backend
- Demo sharing — share your local app with teammates or clients
- API testing — test external integrations against your local server