Everything you need to know.

Getting started

What is tunnels.io?

tunnels.io is a secure tunneling service that exposes your local development servers, APIs, and services to the public internet. Whether you are testing webhooks from Stripe or GitHub, demoing an application to a client, or debugging a mobile app that needs to reach your local backend, tunnels.io creates an encrypted tunnel from a public URL directly to a port on your machine.

When you start a tunnel, you get a public URL such as https://myapp.tunnels.host. Any HTTP or TCP traffic sent to that URL is forwarded through an encrypted TLS connection to your local service. No firewall config, no router port-forwarding, no remote deploy.

System requirements

The client is a single static binary with no external dependencies.

Quick install (recommended)

One command. The installer detects your OS and architecture, downloads the correct binary, verifies the checksum, and installs it.

# Linux, macOS, FreeBSD
curl -fsSL https://tunnels.io/install.sh | bash

# Or with wget
wget -qO- https://tunnels.io/install.sh | bash

# Windows (PowerShell)
Invoke-WebRequest -Uri https://download.tunnels.io/0.0.70/windows/amd64/tunnels.exe -OutFile tunnels.exe

On Linux, macOS, and FreeBSD the installer places the binary in /usr/local/bin/tunnels (or ~/.local/bin/tunnels without sudo).

Manual installation

Prefer to install by hand? Download from the Downloads page or:

# Linux (amd64)
curl -Lo tunnels https://download.tunnels.io/0.0.70/linux/amd64/tunnels
# macOS (Apple Silicon)
curl -Lo tunnels https://download.tunnels.io/0.0.70/darwin/arm64/tunnels
chmod +x tunnels
sudo mv tunnels /usr/local/bin/

Verify the installation:

tunnels version
# 0.0.70

Creating your first tunnel

Have a local server on port 8000? Expose it:

tunnels http 8000

tunnels.io connects, allocates a public URL, and forwards traffic:

Tunnel Status: online
Version:       0.0.70
Web Interface: http://127.0.0.1:4040
Forwarding:    https://a1b2c3d4.tunnels.host -> http://localhost:8000

Signing up and getting an auth token

An account unlocks static subdomains, multiple tunnels, TCP, and higher limits:

1. Visit tunnels.io/signup and create your account.
2. Verify your email via the link sent to your inbox.
3. Your initial CLI token (tnl_…) is shown in your dashboard. Copy it.
4. Create additional tokens from Account > API Tokens.

Using your auth token

tunnels config add-authtoken tnl_xxxxxxxxxxxxxxxxxx
tunnels http 8000

Installation

tunnels.io ships as a single static binary, no dependencies, runtimes, or package managers. Fastest path:

# Automatic install (detects OS + architecture)
curl -fsSL https://tunnels.io/install.sh | bash

Linux

amd64, arm64, 386, and arm.

curl -fsSL https://tunnels.io/install.sh | bash
# Or manual (amd64)
curl -Lo tunnels https://download.tunnels.io/0.0.70/linux/amd64/tunnels
chmod +x tunnels && sudo mv tunnels /usr/local/bin/ && tunnels version

macOS

Intel (amd64) and Apple Silicon (arm64).

# Apple Silicon
curl -Lo tunnels https://download.tunnels.io/0.0.70/darwin/arm64/tunnels
chmod +x tunnels

Windows

# PowerShell
Invoke-WebRequest -Uri https://download.tunnels.io/0.0.70/windows/amd64/tunnels.exe -OutFile tunnels.exe
.\tunnels.exe version

FreeBSD

curl -Lo tunnels https://download.tunnels.io/0.0.70/freebsd/amd64/tunnels
chmod +x tunnels && sudo mv tunnels /usr/local/bin/

Verifying with SHA-256 checksums

Every release includes checksums; the install script verifies automatically. Manually:

curl -fsSL https://download.tunnels.io/checksums.json
sha256sum tunnels          # Linux
shasum -a 256 tunnels      # macOS

Adding to PATH

CLI reference

Basic syntax

tunnels [options] <local-address>

The <local-address> is the local service to expose: a port (8080), host:port (localhost:8080), or IP:port. A bare port assumes localhost.

Command-line flags

Usage examples

# Basic HTTP tunnel
tunnels localhost:3000

# Authenticated, static subdomain (Pro+)
tunnels --authtoken tnl_abc123 --subdomain myapi localhost:8080
# -> https://myapi.tunnels.host

# TCP tunnel for a database
tunnels --proto tcp --authtoken tnl_abc123 localhost:5432


# Debug logging to a file
tunnels --log /tmp/tunnels-debug.log --log-level debug localhost:8000

# Start all tunnels from config
tunnels --config ./my-tunnels.yaml start-all

Configuration

Settings live in ~/.tunnels, a YAML file the client reads on every run. Point at a different file with --config path/to/file. The easiest way to create it is tunnels config add-authtoken TOKEN, which writes the file for you.

File format

Note the shape of proto: it is a map of protocol to local address, not a string. There is no separate addr field.

# ~/.tunnels
server_addr: tunnels.host:443
auth_token: tnl_xxxxxxxxxxxxxxxxxxxxxxxx
inspect_addr: 127.0.0.1:4040

tunnels:
  webapp:
    subdomain: myapp
    proto:
      http: localhost:3000
  database:
    proto:
      tcp: localhost:5432

Start them with tunnels start webapp, or tunnels start-all.

Configuration fields

Custom domains

On Gold and Premium plans, use your own domain instead of a *.tunnels.host subdomain:

1. Add a CNAME pointing your domain to tunnels.host:

   myapp.example.com    CNAME    tunnels.host.

2. Wait for DNS propagation (5-30 min typical).
3. Start with the -hostname flag:

   tunnels --hostname myapp.example.com --authtoken tnl_xxx localhost:3000

TLS certificates for custom domains are provisioned and renewed automatically via Let's Encrypt.

Environment variables

The client reads the variables below. Note the prefix is TUNELS_ with a single N, which does not match the product name. There is no environment override for the auth token: set it in the config file with tunnels config add-authtoken, or pass --authtoken.

API reference

The REST API manages your account, tokens, subscriptions, and usage metrics. All responses are JSON.

Base URL

https://tunnels.io/api/v1

Authentication

Authenticate with a JWT Bearer token (from login) or a CLI token, in the Authorization header. JWT access tokens expire after 15 minutes; CLI tokens don't expire unless revoked.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...     # JWT
Authorization: Bearer tnl_xxxxxxxxxxxxxxxx     # CLI token

Response format

// Success
{ "data": { ... }, "error": null }
// Error
{ "data": null, "error": "Description of what went wrong" }

Endpoints

{ "email": "[email protected]", "password": "MySecureP@ss1", "first_name": "Jane" }

{ "access_token": "eyJ…", "refresh_token": "eyJ…", "token_type": "Bearer" }

HTTP status codes

Protocols

Two transport protocols: HTTP/HTTPS and TCP. TCP requires a paid plan.

HTTP/HTTPS tunneling

The default. You get a public HTTPS URL (e.g. https://myapp.tunnels.host); the server terminates TLS and forwards plain HTTP to your local service.

• Automatic HTTPS — every tunnel gets a valid TLS cert, no config.
• Request inspection — the local UI at localhost:4040.
• Host header rewriting — for virtual-host local setups.
• WebSocket support — wss:// works automatically.

TCP tunneling

Forward raw TCP for databases, SSH, game servers (Pro+). You get a public host:port like 0.tcp.tunnels.host:12345.

# PostgreSQL
tunnels --proto tcp --authtoken tnl_xxx localhost:5432
# psql -h 0.tcp.tunnels.host -p 12345 -U user db

# SSH
tunnels --proto tcp --authtoken tnl_xxx localhost:22

Protocol availability by plan

Security

TLS encryption

All traffic between the internet and the server is TLS 1.2+. The control channel between client and server uses a dedicated TLS connection. HTTP tunnels automatically receive a valid HTTPS certificate; the data channel is encrypted for TCP tunnels too.

Authentication methods

• Basic Auth (Pro+) — tunnels -auth="user:password" localhost:8000
• OAuth / Google (Pro+) — restrict access to Google-authenticated users.
• IP allowlisting (Gold/Premium) — tunnels -cidr-allow="203.0.113.0/24" localhost:8000

Token security

CLI tokens (tnl_) are 64+ chars of cryptographically random data, the keys to your account.

Best practices

Plans & limits

Plan comparison

Current prices, bandwidth allowances, request-rate limits and tunnel counts are on the pricing page, which reads them live from the plan catalog.

The Student plan requires verification with a valid university email address.

Rate limiting (RPS)

Each plan has a max requests-per-second. A token-bucket algorithm with a burst multiplier allows short spikes at 2-5x. Requests over the limit get a 429 from the server, your local service never sees them.

Bandwidth enforcement

• 80% usage — email notification.
• 100% usage — a 24-hour grace period; traffic keeps flowing.
• Grace expired — new connections denied until next period or upgrade.

Troubleshooting

Enabling debug logs

tunnels --log stdout --log-level debug localhost:8000
# Or to a file for support
tunnels --log /tmp/tunnels-debug.log --log-level debug localhost:8000

Deployment

Integrate tunnels.io into CI/CD pipelines, Docker workflows, and team setups for staging and deploy previews.

GitHub Actions example

# .github/workflows/e2e-tests.yml
name: E2E Tests
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install tunnels
        run: curl -fsSL https://tunnels.io/install.sh | bash
      - name: Start tunnel
        env: { TUNELS_NO_UPDATE_CHECK: "1" }
        run: |
          tunnels config add-authtoken ${{ secrets.TUNNELS_TOKEN }}
          tunnels --subdomain pr-${{ github.event.number }} http 3000 &

Deploy previews for pull requests

Give every PR its own public URL using the PR number as the subdomain: https://pr-42.tunnels.host. Post the URL as a bot comment so reviewers click once.

Docker integration

# docker-compose.yml
services:
  app:
    build: .
    ports: ["3000:3000"]
  tunnel:
    image: alpine:latest
    depends_on: [app]
    environment: ["TUNNELS_TOKEN=${TUNNELS_TOKEN}"]
    command: sh -c "wget -qO- https://tunnels.io/install.sh | bash && tunnels config add-authtoken $TUNNELS_TOKEN && tunnels --subdomain myapp http app:3000"

Team collaboration

1. Each developer has a personal account + token.
2. CI/CD uses a dedicated service-account token stored as a repo secret.
3. Subdomain convention: {project}-{developer} (e.g. api-jane).
4. Shared staging: a team service account for always-on tunnels.