Tunnels Overview

Tunnels allow you to expose local development servers to the public internet through your self-hosted Expose server.

How Tunnels Work

Your Mac                         Your VPS                        Internet
┌──────────┐                    ┌──────────────┐                ┌──────────┐
│ localhost│◄──── WebSocket ───►│expose-server │◄──── HTTPS ───►│ Visitors │
│ :3000    │     (persistent)   │              │                │          │
└──────────┘                    └──────────────┘                └──────────┘

1. The macOS app connects to your server via WebSocket
2. When you expose a port, it registers a subdomain
3. Requests to https://subdomain.expose.domain.com are forwarded through the WebSocket
4. The app proxies requests to your local server
5. Responses flow back through the same path

Key Features

Single Connection

All traffic flows through one WebSocket connection per tunnel. Multiple concurrent requests are multiplexed using stream IDs.

Automatic TLS

Your server provides TLS certificates via Let’s Encrypt. Local traffic is always encrypted in transit.

Low Latency

Traffic routes directly through your infrastructure — no third-party servers in the path.

WebSocket Support

Full WebSocket passthrough for real-time applications. WebSocket connections from visitors are tunneled through to your local server.

Tunnel States

State	Description
Connecting	Establishing WebSocket connection
Authenticating	Verifying API key
Registering	Requesting subdomain
Connected	Tunnel active, ready for traffic
Reconnecting	Connection lost, attempting to reconnect
Disconnected	Tunnel closed
Error	Failed to connect

Metrics

Expose tracks real-time metrics for each tunnel:

• Bytes In: Total data received from visitors
• Bytes Out: Total data sent to visitors
• Request Count: Number of HTTP requests
• Active Streams: Current concurrent requests

Use Cases

Share with Clients

Expose your local work to get feedback without deploying:

https://preview.expose.yourdomain.com → localhost:3000

Webhook Testing

Receive webhooks from services like Stripe or GitHub:

https://webhooks.expose.yourdomain.com/stripe → localhost:3000/stripe

Mobile Testing

Test your app on real mobile devices:

https://myapp.expose.yourdomain.com → localhost:3000

Team Collaboration

Share work-in-progress with teammates:

https://feature-x.expose.yourdomain.com → localhost:3000

Limitations

• Tunnels require an active network connection
• Large file transfers may be slower than direct connections
• Your local server must be running to respond to requests