Everything you need to know.

Getting Started

What is Tunels?

Tunels 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, Tunels creates an encrypted tunnel from a public URL directly to a port on your machine.

When you start a tunnel, Tunels assigns you a public URL such as https://myapp.tunnels.solutions. Any HTTP, TCP, or UDP traffic sent to that URL is forwarded through an encrypted TLS connection to your local service. You do not need to configure firewalls, set up port forwarding on your router, or deploy anything to a remote server.

System Requirements

Tunels runs on all major operating systems and architectures. The client is a single static binary with no external dependencies.

Quick Install (Recommended)

Install Tunels with a single command. The installer detects your OS and architecture automatically, downloads the correct binary, verifies the checksum, and installs it.

On Linux, macOS, and FreeBSD, the installer places the binary in /usr/local/bin/tunels (or ~/.local/bin/tunels if sudo is not available). On Windows (Git Bash), it saves tunels.exe to the current directory.

Manual Installation

If you prefer to install manually, download the binary for your platform from the Downloads page or use the command line:

Verify the installation:

Creating Your First Tunnel

Suppose you have a local web server running on port 8000. To expose it to the internet, simply run:

Tunels will connect to the tunnel server, allocate a public URL, and begin forwarding traffic:

Signing Up and Getting an Auth Token

While you can use Tunels without an account on the free Basic plan (with a random subdomain), creating an account unlocks static subdomains, multiple tunnels, TCP/UDP protocols, and higher limits. To sign up:

1. Visit tunels.io/signup and create your account.
2. Verify your email address using the link sent to your inbox.
3. After verification, your initial CLI token (tun_live_...) is shown in your dashboard. Copy it.
4. You can also create additional tokens from Account > API Tokens.

Using Your Auth Token

Pass your authentication token when starting a tunnel to access your plan features:

Or save it in a configuration file so you do not have to pass it every time (see Configuration):

Installation

Tunels is distributed as a single static binary. There are no dependencies, runtimes, or package managers required. The fastest way to install is with our install script:

The script downloads the correct binary, verifies the SHA-256 checksum, and installs it to your PATH. If you prefer to install manually, see the platform-specific instructions below.

Linux

Available for amd64, arm64, 386, and arm architectures.

On Linux systems with systemd, you can also set up Tunels as a service for persistent tunnels. See the Deployment section for details.

macOS

Available for both Intel (amd64) and Apple Silicon (arm64) Macs.

Windows

Available for amd64, 386, and arm64. Download the .exe binary.

To add Tunels to your system PATH on Windows, move tunels.exe to a directory that is already in your PATH, or add a new directory:

FreeBSD

Available for amd64 and arm64.

Verifying with SHA-256 Checksums

Every release includes SHA-256 checksums to verify the integrity of your download. The install script verifies checksums automatically. For manual verification:

Adding to PATH

For convenience, move the Tunels binary to a directory in your system PATH so you can invoke it from anywhere without specifying the full path.

CLI Reference

Basic Syntax

The general syntax for the Tunels CLI is:

The <local-address> is the address of the local service you want to expose. It can be a port number (8080), a host and port (localhost:8080), or an IP and port (192.168.1.100:3000). If you specify only a port number, Tunels assumes localhost as the host.

Command-Line Flags

The following flags control tunnel behavior. All flags are optional except the local address.

Usage Examples

Basic HTTP tunnel

Authenticated tunnel with a static subdomain

TCP tunnel for a database

UDP tunnel for DNS

Custom Host header rewriting

Debug logging to a file

Start all tunnels from config

Disable the web inspector

Configuration

Instead of passing flags on every invocation, you can define your settings in a tunels.yml configuration file. Tunels automatically looks for tunels.yml in the current working directory. You can specify a different path with -config=path/to/file.yml.

File Format

The configuration file uses YAML format. Here is a complete example with all available fields:

Configuration Fields

Tunnel Definition Fields

Each entry under tunnels supports the following fields:

Custom Domains

On Gold and Premium plans, you can use your own domain name instead of a *.tunnels.solutions subdomain. To set up a custom domain:

1. Add a CNAME record in your DNS provider pointing your domain to tunnels.solutions:
   myapp.example.com CNAME tunnels.solutions.
2. Wait for DNS propagation (typically 5-30 minutes, up to 48 hours for some providers).
3. Start your tunnel with the -hostname flag:
   tunels -hostname=myapp.example.com -authtoken=tun_live_xxx localhost:3000

Tunels automatically provisions and renews TLS certificates for custom domains using Let's Encrypt.

Environment Variable Overrides

You can set configuration values through environment variables. This is especially useful in CI/CD pipelines and containerized environments where you do not want to store tokens in files.

Environment variables take precedence over the config file, which takes precedence over command-line flag defaults. Explicit command-line flags always have the highest priority.

API Reference

The Tunels REST API allows you to manage your account, tokens, subscriptions, and view usage metrics programmatically. All API endpoints return JSON responses.

Base URL

Authentication

API requests are authenticated using either a JWT Bearer token (obtained from the login endpoint) or a CLI token (for machine-to-machine access). Include the token in the Authorization header:

JWT access tokens expire after 15 minutes. Use the refresh endpoint to obtain a new access token. CLI tokens do not expire unless explicitly revoked.

Response Format

All responses follow a consistent JSON envelope:

Endpoints

HTTP Status Codes

Protocols

Tunels supports three transport protocols for tunneling: HTTP/HTTPS, TCP, and UDP. Each is suited to different use cases and availability depends on your plan.

HTTP/HTTPS Tunneling

HTTP is the default and most common protocol. When you create an HTTP tunnel, Tunels assigns a public HTTPS URL (e.g., https://myapp.tunnels.solutions). All traffic between the public internet and the Tunels server is encrypted with TLS. The Tunels server terminates TLS and forwards plain HTTP to your local service.

Key features of HTTP tunnels:

• Automatic HTTPS — Every tunnel gets a valid TLS certificate. No configuration needed.
• Request inspection — The local web UI at localhost:4040 shows all HTTP requests and responses with full headers and bodies.
• Host header rewriting — If your local server uses virtual hosts, you can rewrite the Host header.
• WebSocket support — WebSocket connections (wss://) work automatically over HTTP tunnels. No special configuration is required.

TCP Tunneling

TCP tunnels forward raw TCP connections to your local service. This is essential for non-HTTP protocols such as databases, SSH, game servers, or any custom TCP-based application. TCP tunnels require a Pro plan or higher.

When you create a TCP tunnel, Tunels assigns a public host:port pair (e.g., 0.tcp.tunnels.solutions:12345). Remote clients connect to this address and their TCP connections are forwarded directly to your local service.

UDP Tunneling

UDP tunnels forward UDP datagrams to your local service. This is useful for DNS servers, gaming servers, VoIP applications, and IoT devices that use UDP-based protocols. UDP tunnels require a Gold plan or higher.

WebSocket Support

WebSocket connections work automatically over HTTP tunnels. When a client sends an HTTP Upgrade: websocket request to your tunnel URL, Tunels correctly handles the protocol upgrade and maintains the persistent bidirectional connection between the remote client and your local WebSocket server.

No special flags or configuration are needed. If your local server supports WebSocket, it works through the tunnel:

Protocol Availability by Plan

Security

Security is fundamental to Tunels. Every tunnel connection is encrypted, tokens are securely stored, and multiple layers of access control are available to protect your exposed services.

TLS Encryption

All traffic between the internet and the Tunels server is encrypted with TLS 1.2+. The control channel between the Tunels client on your machine and the server uses a dedicated TLS connection on port 4443. HTTP tunnels automatically receive a valid HTTPS certificate, so visitors to your tunnel URL always connect over HTTPS.

The data channel between the Tunels client and server is also encrypted, meaning your local traffic is never transmitted in plaintext over the internet even for TCP and UDP tunnels.

Authentication Methods

In addition to the base tunnel URL, you can add authentication layers to restrict who can access your tunnels. These are particularly valuable when exposing staging environments or sensitive internal services.

Basic Auth Protection

Add HTTP Basic Authentication to your tunnel so visitors must enter a username and password before accessing your service. Available on Pro plans and above.

OAuth / Google Auth (Pro+)

On Pro plans and above, you can restrict tunnel access to users who authenticate with their Google account. This is ideal for sharing staging environments with teammates who all have company Google accounts.

IP Whitelisting / Allowlisting

On Gold and Premium plans, you can restrict tunnel access to specific IP addresses or CIDR ranges. This is the most restrictive form of access control and is recommended for production-like environments.

Token Security

Your CLI tokens (prefixed with tun_live_) are the keys to your Tunels account. They are 64+ characters of cryptographically random data and are used to authenticate tunnel connections and identify your plan.

Best Practices

Plans & Limits

Tunels offers five plans designed for different needs, from hobbyists exploring the tool to enterprises running production infrastructure. All paid plans include a 14-day free trial.

Plan Comparison

* Student plan requires verification with a valid university email and proof of enrollment.

Rate Limiting (RPS)

Each plan has a maximum requests-per-second (RPS) limit. This is the sustained rate of HTTP requests your tunnel can handle. Tunels uses a token bucket algorithm with a burst multiplier, meaning short spikes above the limit are allowed:

• Sustained rate — The long-term average RPS allowed by your plan.
• Burst multiplier — Allows temporary spikes at 2-5x the sustained rate (varies by plan). The burst bucket drains quickly, so sustained traffic must stay at or below the limit.
• Exceeded response — Requests that exceed the rate limit receive a 429 Too Many Requests response from the Tunels server. Your local service never sees these requests.

Bandwidth Enforcement

Bandwidth usage is tracked per billing period (monthly). Both inbound and outbound traffic through your tunnels counts toward your limit. When you approach your limit:

• 80% usage — You receive an email notification.
• 100% usage — A 24-hour grace period begins. Traffic continues to flow during the grace period.
• Grace period expired — New tunnel connections are denied until the next billing period or until you upgrade your plan.

You can monitor your current bandwidth usage at any time from the account billing page or via the GET /api/v1/metrics/current API endpoint.

Troubleshooting

This section covers the most commonly encountered issues and their solutions. If you do not find your issue here, enable debug logging (see below) and contact support.

Common Issues

Enabling Debug Logs

When troubleshooting, enable full debug logging to capture detailed information about the tunnel lifecycle, TLS handshakes, and message frames:

When contacting support, include the debug log file and the output of tunels version. This dramatically speeds up diagnosis.

Deployment

Tunels is not just a development tool. You can integrate it into CI/CD pipelines, Docker workflows, and team collaboration setups for staging environments and deploy previews.

CI/CD Integration

Use Tunels in your CI/CD pipeline to create temporary public URLs for integration testing, end-to-end tests, or deploy previews. The tunnel starts before your tests run and stops when the job finishes.

GitHub Actions Example

Deploy Previews for Pull Requests

Give every pull request its own public URL so reviewers can interact with the changes without checking out the branch locally. Use the PR number as the subdomain for predictable URLs:

• https://pr-42.tunnels.solutions for PR #42
• https://pr-123.tunnels.solutions for PR #123

Add a bot comment to the PR with the preview URL so reviewers can access it with one click.

Docker Integration

Run Tunels alongside your application in a Docker Compose setup. This is useful for development environments that already use Docker.

Environment-Based Configuration

Use environment variables to configure Tunels differently across environments. This avoids storing tokens in configuration files and makes it easy to use different settings in development, CI, and staging.

Team Collaboration

For teams, each developer should have their own Tunels account and token. This ensures proper attribution, separate tunnel limits, and the ability to revoke access individually. Recommended setup:

1. Each developer creates a personal Tunels account and generates their own token.
2. CI/CD pipelines use a dedicated service account token stored as a repository secret.
3. Convention for subdomains: Use a pattern like {project}-{developer} (e.g., api-jane, api-john) so team members know which tunnel belongs to whom.
4. Shared staging: Use a team service account for always-on staging tunnels that the whole team can access.