Documentation

Everything you need to know about TunnelDev

Installation

Install TunnelDev CLI globally using npm:

npm install -g tunneldev

This makes the tunneldev command available system-wide.

Authentication

Before creating tunnels, you need to authenticate with your API key:

  1. Sign up at tunneldev.vercel.app/signup
  2. Go to your dashboard
  3. Copy your API key (click the "Copy" button)
  4. Login via CLI:
tunneldev login YOUR_API_KEY

Your API key is stored securely in ~/.tunneldev/config.json

Your First Tunnel

Start a local server (any port), then create a tunnel:

tunneldev 3000

You'll get a public URL that forwards to your localhost:

✓ Tunnel created successfully!
──────────────────────────────────────
Tunnel URL: https://tunneldev.onrender.com/t/a8f3c2
Local URL:  http://localhost:3000
──────────────────────────────────────
Forwarding traffic... Press Ctrl+C to stop

Share the tunnel URL with anyone. All requests will be forwarded to your localhost.

How It Works

TunnelDev uses WebSocket connections to create secure tunnels:

  1. Your CLI connects to TunnelDev servers via WebSocket
  2. A public URL is generated for your tunnel
  3. When someone visits the URL, the request is sent through WebSocket to your CLI
  4. Your CLI forwards it to your localhost
  5. The response travels back through the same path

Security Note

All connections use TLS encryption. Your localhost remains completely private and secure.

Tunnels

Tunnels are the core concept in TunnelDev. Each tunnel:

  • Has a unique public URL
  • Forwards to a specific localhost port
  • Remains active while the CLI is running
  • Automatically closes when you stop the CLI (Ctrl+C)

Free tier: 3 simultaneous tunnels
Pro tier: 10 simultaneous tunnels
Max/Team: Unlimited tunnels

Requests

Every HTTP request through your tunnel is logged:

[14:23:15] 1. GET /api/users
  → 200 OK

[14:23:18] 2. POST /api/create
  → 201 Created

Request history is stored based on your plan:

  • Free: 24 hours
  • Pro/Max: 90 days
  • Team: 1 year

Commands

tunneldev login <api-key>

Authenticate with your API key

Example:

tunneldev login abc123def456...
tunneldev [port]

Start a tunnel to localhost:port (default: 3000)

Example:

tunneldev 8080
tunneldev start [port]

Same as above, explicit start command

Example:

tunneldev start 5500
tunneldev help

Show help message

Example:

tunneldev help

Options

Environment variables you can set:

TUNNELDEV_API_URL

Override the default API server URL

Default: https://tunneldev-backend.onrender.com

PORT

Default port to tunnel if not specified

Default: 3000

Webhooks

TunnelDev is perfect for testing webhooks from services like Stripe, GitHub, Twilio, etc.

Example with Stripe:

  1. Start your local server that handles webhooks
  2. Create a tunnel: tunneldev 4000
  3. Copy the tunnel URL
  4. Add it to Stripe dashboard as your webhook endpoint
  5. Test payments and see webhooks arrive in real-time

Pro Tip

Keep your CLI running in a separate terminal. Use Ctrl+C only when you're done testing.

Team Sharing (Max/Team Plans)

Share tunnels with your team members:

  • Multiple team members can monitor the same tunnel
  • See all requests in real-time
  • Comment on specific requests
  • Perfect for pair programming and debugging

Available on Max (5 users) and Team (unlimited users) plans.

Troubleshooting

Error: Not authenticated

You need to login first. Run: tunneldev login <your-api-key>

Error: Local server not running on port X

Make sure your local server is actually running on that port before creating the tunnel.

Tunnel closed unexpectedly

Check your internet connection. The CLI needs to stay connected via WebSocket.

Can't install globally

Try: sudo npm install -g tunneldev (Mac/Linux) or run terminal as Administrator (Windows)

Need Help?

Can't find what you're looking for? We're here to help.

Email SupportTelegram