How It Works

Proxer has two sides. The public server listens where browsers and reverse proxies can reach it. The client runs next to the private service and dials out to the server. The private network does not need an inbound firewall rule for the app.

One listener, reserved paths

The public server uses one HTTP/WebSocket listener. These paths are reserved by Proxer:

/__proxer__/control
/__proxer__/health/live
/__proxer__/health/ready

There is no --control-path option. Clients receive a base URL such as wss://proxy.example.com; Proxer appends /__proxer__/control internally.

Control connection

proxer http opens a WebSocket connection to /__proxer__/control. After token authentication, it registers a chosen subdomain route, an explicit root route, or asks the server to assign a random subdomain.

When a public request arrives, the server creates a tunnel stream and sends request frames over that existing control connection. The client turns those frames into a request to 127.0.0.1:<port>, then sends response headers and body chunks back on the same stream.

Multiple public requests can share one control connection because every stream has its own streamId.

Request flow

1. A browser or reverse proxy sends a request to the public Proxer server.
2. The server reads the effective host and finds the matching root or subdomain route.
3. The server opens a tunnel stream over the registered client’s control connection.
4. The client forwards the request to 127.0.0.1:<port>.
5. Response headers and body chunks return over that tunnel stream.
6. The public server writes the response back to the original caller.

HTTP streaming and Server-Sent Events are forwarded as chunks, not buffered as one whole response. WebSocket upgrades become bidirectional tunnel streams after the same host-routing step.

Reconnect behavior

If an established control connection drops, the client cleans up active streams and tries to reconnect. When the server is reachable at the same URL, the client authenticates and registers again. Auto-assigned subdomains stay stable across reconnects during the same client run.

Initial startup is stricter. If you start the client while the server is unavailable, the command may fail before the reconnect loop exists. Start the server first.

What Proxer will not guess

Proxer does not route a request to the only connected client just because there is one. The host must match the root domain route or a registered subdomain route. In practice, this avoids a class of confusing mistakes when several people or services share one tunnel server.