ProxyHub

Expose localhost to the internet. Open-source and self-hostable.

Quick Start

npx proxyhub -p 3000

That's it! Your local server running on port 3000 is now accessible from the internet.

Installation

Using npx (no install needed)

npx proxyhub -p <port>

Global install

npm install -g proxyhub
proxyhub -p <port>

Usage

Basic

proxyhub -p 3000

Interactive Setup

Running proxyhub with no arguments launches an interactive wizard (same as proxyhub init). It prompts for mode, port, inspector port, token, auth key, and debug, prints the equivalent CLI command, then starts. Pass any flag to skip the wizard.

proxyhub          # wizard
proxyhub init     # wizard (explicit)

Request Inspector

Enable the built-in inspector to monitor all proxied requests and responses through a local web UI:

# Enable inspector (opens on port + 1000 by default)
proxyhub -p 3000 --inspect

# Custom inspector port
proxyhub -p 3000 --inspect --inspect-port 9000

Once enabled, open the inspector URL shown in the terminal (e.g., http://localhost:4000) to view requests in real-time.

Inspector features:

• Filter by method, status code, and path
• View full request/response headers and bodies
• Resend captured requests with one click
• API Composer — click "Compose" to build requests from scratch, or "Edit in Composer" on any captured request to pre-fill the form with its method, URL, headers, and body
• cURL export — expand the cURL section on any request detail page to get a ready-to-copy command
• Light/dark theme

Mock Mode

Define mock API responses without needing a real backend server. Mock mode includes a web UI for managing mocks and supports exact, prefix, and regex path matching.

# Pure mock mode (no local server needed)
proxyhub --mock

# Hybrid mode (mocked paths return mock data, others proxy to localhost)
proxyhub --mock -p 3000

# Inspector automatically enables mock mode
proxyhub -p 3000 --inspect

Once running, open the Mock Manager URL shown in the terminal (e.g., http://localhost:3001/mocks) to create and manage mocks.

Mock features:

• Pure mock mode — no local server required, define all responses via the UI
• Hybrid mode — combine mocks with a real backend; mocked paths return mock data, non-mocked paths proxy normally
• Path matching — exact, prefix, or regex matching with configurable priority
• Response customization — set status codes, headers, body, and response delay
• Inspector integration — mocked requests appear in the inspector with a MOCK badge
• Enable/disable individual mocks without deleting them

Token Protection

Secure your tunnel so only requests with the correct token can access it:

proxyhub -p 3000 --token mysecrettoken

Requests must then include the X-Proxy-Token header:

curl -H "X-Proxy-Token: mysecrettoken" https://your-tunnel.proxyhub.cloud/

Inspector Only (no tunnel)

Browse previously logged requests and manage mocks locally without opening a tunnel:

proxyhub --inspector-only

# Custom inspector port (default 3001)
proxyhub --inspector-only --inspect-port 9000

Debug Mode

proxyhub -p 3000 --debug

CLI Options

| Option | Description | |--------|-------------| | -p, --port <port> | Port number to proxy | | -m, --mock | Enable mock mode | | -t, --token <token> | Token for tunnel protection | | -i, --inspect | Enable request inspector UI | | --inspect-port <port> | Port for inspector UI (default: port + 1000, or 3001 in inspector-only mode) | | --inspector-only | Run only the inspector UI against logged requests (no tunnel) | | -k, --auth-key <key> | Authentication key for the ProxyHub server | | -d, --debug | Enable debug mode | | -V, --version | Output version number | | -h, --help | Display help |

One of --port, --mock, or --inspector-only is required. Using --inspect automatically enables mock mode. Running proxyhub with no arguments starts the interactive wizard.

Self-Hosted Server

Connect to your own ProxyHub server using environment variables:

PROXYHUB_SOCKET_URL=https://your-server.com proxyhub -p 3000

See the self-hosting guide for server setup instructions.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PROXYHUB_SOCKET_URL | https://connect.proxyhub.cloud | ProxyHub server URL | | PROXYHUB_SOCKET_PATH | /socket.io | Socket.IO path | | PROXYHUB_TOKEN | - | Token for tunnel protection | | PROXYHUB_AUTH_KEY | - | Authentication key for the server | | PROXYHUB_ALLOW_INSECURE | - | Allow self-signed TLS certificates |

How It Works

1. Client connects to the ProxyHub server via WebSocket
2. Server assigns a unique public URL (e.g., https://abc123.proxyhub.cloud)
3. Incoming requests to that URL are forwarded through the WebSocket to the client
4. Client proxies them to your local server and streams responses back

Security

Server Authentication

If the ProxyHub server requires authentication, provide the shared key:

proxyhub -p 3000 --auth-key your-secret-key

# Or via environment variable
PROXYHUB_AUTH_KEY=your-secret-key proxyhub -p 3000

TLS Certificate Verification

TLS certificate verification is enabled by default. To connect to servers with self-signed certificates:

PROXYHUB_ALLOW_INSECURE=1 proxyhub -p 3000

Tunnel IDs

Tunnel IDs are cryptographically random and persisted in ~/.proxyhub/tunnel-ids.json for stability across restarts.

The server also enforces rate limits: 5000 HTTP requests per 10-minute window and 30 WebSocket connections per minute per IP. These are configurable via server environment variables (RATE_LIMIT_MAX_REQUESTS, RATE_LIMIT_WINDOW_MS, SOCKET_MAX_CONNECTIONS_PER_MINUTE).

See the SECURITY.md for full security documentation.

Links

• GitHub
• Documentation
• Self-Hosting Guide

License

MIT