Tunnel Client

A production-ready tunnel client for creating secure tunnels to local services.

Installation

npm install @codemancers/tunnel-client

Or use npx to run without installation:

npx @codemancers/tunnel-client --port 3001 --host https://tunnel.c9s.dev

Usage

Command Line

tunnel-client --port 3001 --host https://local-tunnel.fly.dev --subdomain myapp

Arguments

• --port <port> - The local port to tunnel (required)
• --host <url> - The tunnel server URL (default: http://localhost:3000)
• --subdomain <name> - Optional subdomain name for the tunnel

Environment Variables

You can also configure the client using environment variables:

• TUNNEL_PORT - The local port to tunnel
• TUNNEL_HOST - The tunnel server URL
• TUNNEL_SUBDOMAIN - Optional subdomain name
• TUNNEL_TARGET - Target URL (alternative to port)

Examples

# Basic usage with local server
tunnel-client --port 3001

# With custom server and subdomain
tunnel-client --port 3001 --host https://tunnel.c9s.dev --subdomain myapp

# Using environment variables
export TUNNEL_PORT=3001
export TUNNEL_HOST=https://tunnel.c9s.dev
export TUNNEL_SUBDOMAIN=myapp
tunnel-client

How It Works

1. The client connects to the tunnel server and requests a new tunnel
2. The server allocates a unique tunnel ID and returns the public URL
3. The client establishes a WebSocket connection to the tunnel
4. All HTTP requests to the public URL are proxied through the WebSocket to your local service

Requirements

• Node.js >= 18.0.0

License

MIT