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.

Features

• Instant Setup - No account required, just run one command
• Request Inspector - Built-in web UI to monitor all proxied requests and responses in real-time
• API Composer - Postman-like request builder inside the inspector to craft and send HTTP requests
• cURL Export - Generate copy-ready cURL commands from any captured request
• Mock Mode - Define mock responses for API paths without a running backend, with a web UI to manage mocks
• Token Protection - Secure your tunnels with authentication tokens
• Self-Hostable - Run your own ProxyHub server
• Session Timeouts - Configurable session duration limits
• WebSocket Support - Full duplex communication via Socket.IO

Installation

Using npx (no install)

npx proxyhub -p <port>

Global install

npm install -g proxyhub
proxyhub -p <port>

Usage

Basic Usage

# Expose local port 3000
proxyhub -p 3000

# With debug output
proxyhub -p 3000 --debug

Interactive Setup

Running proxyhub with no arguments launches an interactive wizard — the same one you get from proxyhub init:

# No args → wizard
proxyhub

# Explicit
proxyhub init

The wizard prompts for mode (proxy / proxy + inspector / hybrid / pure mock / inspector-only), port, inspector port, token, auth key, and debug, then prints the equivalent CLI command before launching. Pass any flag (e.g. -p 3000) to skip the wizard and run directly.

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:

# Using CLI flag
proxyhub -p 3000 --token mysecrettoken

# Using environment variable
PROXYHUB_TOKEN=mysecrettoken proxyhub -p 3000

When token protection is enabled, requests must 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

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.

Commands

Command	Description
init	Interactive wizard that prompts for every option and launches ProxyHub with your choices

Self-Hosting

Docker (Recommended)

docker run -d \
  -p 4000:4000 \
  -e BASE_DOMAIN=your-domain.com \
  -e PROTOCOL=https \
  -e CONNECTION_TIMEOUT_MINUTES=30 \
  ghcr.io/cube-root/proxyhub-server:latest

Docker Compose

services:
  server:
    build:
      context: ./packages/server
      dockerfile: Dockerfile
    container_name: proxyhub-server
    restart: unless-stopped
    ports:
      - "4000:4000"
    environment:
      - PORT=4000
      - BASE_DOMAIN=your-domain.com
      - PROTOCOL=https
      - SOCKET_PATH=/socket.io
      - CONNECTION_TIMEOUT_MINUTES=30

Connect Client to Self-Hosted Server

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

Environment Variables

Server

Variable	Default	Description
PORT	4000	Server port
BASE_DOMAIN	proxyhub.cloud	Base domain for tunnel URLs
PROTOCOL	https	Protocol for generated URLs
SOCKET_PATH	/socket.io	Socket.IO path
CONNECTION_TIMEOUT_MINUTES	30	Session timeout (0 = unlimited)
SOCKET_AUTH_KEY	-	Shared key for socket authentication
ALLOWED_ORIGINS	-	Comma-separated list of allowed CORS origins
RATE_LIMIT_WINDOW_MS	600000	HTTP rate limit window (ms)
RATE_LIMIT_MAX_REQUESTS	5000	Max HTTP requests per window
SOCKET_MAX_CONNECTIONS_PER_MINUTE	30	Max socket connections per IP per minute

Client

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 ProxyHub server via WebSocket
2. Server generates a unique tunnel URL (e.g., https://abc123.proxyhub.cloud)
3. Incoming HTTP requests to the tunnel URL are forwarded to the client
4. Client proxies requests to your local server and streams responses back

Internet Request                     Your Local Server
       |                                    ^
       v                                    |
  ProxyHub Server  <--WebSocket-->  ProxyHub Client
  (proxyhub.cloud)                   (your machine)

Security

ProxyHub includes several security features for production use:

• Socket authentication — set SOCKET_AUTH_KEY on the server and --auth-key on the client to restrict connections
• TLS verification — enabled by default; opt out with PROXYHUB_ALLOW_INSECURE for self-signed certs
• Rate limiting — HTTP (5000 requests/10 min) and WebSocket (30 connections/min per IP) rate limits protect against abuse
• CORS restrictions — configure ALLOWED_ORIGINS to restrict cross-origin access
• Security headers — helmet middleware sets secure HTTP response headers
• Header filtering — hop-by-hop headers are stripped from proxied requests
• Unpredictable tunnel IDs — cryptographically random tunnel URLs

See SECURITY.md for full details, configuration options, and the list of fixed security issues.

Development

# Clone the repository
git clone https://github.com/cube-root/proxyhub.git
cd proxyhub

# Install dependencies
npm install

# Build all packages
npm run build

# Run server locally
cd packages/server && npm run dev

# Run client (in another terminal)
cd packages/client && npm run dev -- -p 3000

License

MIT - Copyright (c) 2024 Abhijith V