Getting Started

This walkthrough uses the common setup: a cheap public server receives traffic, while a laptop or private machine runs the actual app. The private machine only needs outbound access to the public server.

Prerequisites

• A public machine or reverse proxy that can receive HTTP/WebSocket traffic.
• A local HTTP service to expose.
• Node.js 24 or later if you install with npm.

Install

Windows

Download a standalone Windows executable from GitHub Releases.

proxer.exe --version

macOS / Linux

brew install tinyrack-net/tap/proxer

npm

npm install -g @tinyrack/proxer

Docker

docker run --rm tinyrack/proxer --version

Expose one service

The public wss:// and https:// examples assume TLS terminates in front of Proxer, usually at Caddy, Traefik, NGINX, or a load balancer. That proxy should forward HTTP and WebSocket traffic to Proxer over loopback or a private network.

1. Start the public server

   Run this on the machine that receives public traffic:

   proxer server --listen 0.0.0.0:8080 --domain your-server.example.com --token dev-token

   The same port handles public requests and the tunnel control WebSocket.

2. Start a local app

   On the client machine, start any HTTP service. Python is enough for a smoke test:

   python3 -m http.server 3000 --bind 127.0.0.1

3. Register an auto-assigned route

   Omit --subdomain when you want Proxer to assign a random subdomain:

   proxer http 3000 \
     --server wss://your-server.example.com \
     --token dev-token

4. Call the assigned host

   The client prints a subdomain: px-... line and the full public URL. Use that host:

   curl https://px-k7m3q9t2ab.your-server.example.com/

5. Register a subdomain route

   Use --subdomain when you want a named route:

   proxer http 3000 \
     --server wss://your-server.example.com \
     --subdomain demo \
     --token dev-token

6. Call the subdomain host

   curl https://demo.your-server.example.com/

   Use --subdomain @ only when you intentionally want the root host itself to reach the client. This is intended for servers started with --domain.

Caution

dev-token is only for demos and local testing. In a real deployment, set a long random value with PROXER_TOKEN, a container secret, a Kubernetes secret, or your platform’s secret store.

Tip

During local testing, the Host header decides which tunnel receives the request. In production, DNS and your reverse proxy should preserve the original host.

Local-only test

If you do not have DNS ready yet, keep everything on one machine and pass the host header yourself:

python3 -m http.server 3000 --bind 127.0.0.1
proxer server --listen 127.0.0.1:8080 --domain proxy.localhost --token dev-token
proxer http 3000 --server ws://127.0.0.1:8080 --subdomain demo --token dev-token
curl -H 'Host: demo.proxy.localhost' http://127.0.0.1:8080/

Read How It Works for the request flow, or Routing and Trusted Proxies before putting Proxer behind Traefik, Caddy, NGINX, or a load balancer.