Tunnel Fast

Fast and secure tunnel client for exposing local services to the internet.

Features

• Expose local services through secure tunnels
• Token-based authentication
• Path-based routing (no subdomain required)
• Simple CLI interface
• Can be used as a library or CLI tool

Installation

Global installation (CLI)

npm install -g tunnel-fast

Local installation (Library)

npm install tunnel-fast

Usage

CLI

# Basic usage
tunnel-fast start --port 3000 --server https://tunnel.yourdomain.com --key your-master-key

# Using environment variables
export TUNNEL_SERVER=https://tunnel.yourdomain.com
export TUNNEL_MASTER_KEY=your-master-key
tunnel-fast start --port 3000

# Show help
tunnel-fast --help

Using Environment Variables (Optional)

You can set environment variables instead of passing arguments:

export TUNNEL_SERVER=https://tunnel.yourdomain.com
export TUNNEL_MASTER_KEY=your-secret-master-key
tunnel-fast start --port 3000

Programmatic Usage

const TunnelClient = require('tunnel-fast');

const client = new TunnelClient({
  serverUrl: 'https://tunnel.yourdomain.com',
  masterKey: 'your-master-key',
  localPort: 3000
});

client.on('tunnel-created', (data) => {
  console.log('Public URL:', data.publicUrl);
  console.log('Access Token:', data.accessToken);
  console.log('Full URL:', `${data.publicUrl}?token=${data.accessToken}`);
});

client.on('request', (reqData) => {
  console.log(`${reqData.method} ${reqData.path}`);
});

client.on('error', (error) => {
  console.error('Error:', error.message);
});

client.connect();

How it works

1. Client connects to your tunnel server with master key
2. Server validates the master key and creates a tunnel
3. Server returns a unique tunnel ID and access token
4. Your local service is now accessible at: https://server.com/t/{tunnelId}?tunnel-token={accessToken}
5. Requests to that URL are forwarded to your local service

Options

CLI Options

• -p, --port <port> - Local port to expose (default: 3000)
• -s, --server <url> - Tunnel server URL
• -k, --key <key> - Master key for authentication
• -V, --version - Show version number
• -h, --help - Show help

Client Options

new TunnelClient({
  serverUrl: 'https://server.com', // Required: Tunnel server URL
  masterKey: 'your-key',            // Required: Master key for authentication
  localPort: 3000                   // Optional: Local port (default: 3000)
})

Events

The client emits the following events:

• connected - Connected to tunnel server
• tunnel-created - Tunnel successfully created (provides URL and token)
• request - Incoming request received
• error - Error occurred
• disconnected - Disconnected from server

Server Setup

You need to deploy the tunnel server first. See the tunnel-fast-server repository for instructions.

Quick setup:

1. Deploy tunnel-fast-server to your hosting service
2. Set MASTER_KEY environment variable
3. Set PUBLIC_URL to your public server URL
4. Use that server URL with this client

Security

• Master key is required to create tunnels (keep it secret!)
• Each tunnel gets a unique access token
• Tokens are required to access tunnels
• Tokens can be passed via query parameter tunnel-token or X-Tunnel-Token header

License

MIT

Publishing

This package is automatically published to NPM via GitHub Actions. See PUBLISHING.md for details.

Contributing

Pull requests are welcome! For major changes, please open an issue first.