Warren Documentation

Warren is a QUIC-powered reverse tunnel — expose any local TCP or UDP service to the internet with one command.

Installation

Linux / macOS (one-liner)

curl -fsSL https://warrentunnel.online/install.sh | sh

This installs the warren binary to /usr/local/bin.

Manual download

Download the latest release for your platform from GitHub Releases.

# Linux x86_64
curl -Lo warren https://github.com/warrentunnel/warren/releases/latest/download/warren-linux-amd64
chmod +x warren
sudo mv warren /usr/local/bin/

Build from source

git clone https://github.com/warrentunnel/warren
cd warren
cargo build --release
# binary at: target/release/warren

Quick Start

# 1. Create a free account and log in
warren login

# 2. Expose port 3000
warren expose 3000

# Your service is now live at:
https://yourname.warrentunnel.online

Authentication

Warren uses two types of tokens:

• Access tokens — short-lived JWTs (15 min), used by the web dashboard and API. Rotated automatically.
• Tunnel tokens — long-lived opaque tokens used by the CLI to authenticate to the relay. Managed via warren token commands or the dashboard.

Credentials are stored in ~/.warren/credentials.json. On first warren expose, a tunnel token is created automatically.

warren expose

Expose one or more local ports through the warren relay.

warren expose <port> [flags]

# Examples:
warren expose 3000                     # expose localhost:3000
warren expose 8080:127.0.0.1:3000      # remote :8080 → local :3000
warren expose 3000 4000 5000           # expose multiple ports

warren token

Manage tunnel tokens for your account.

warren token list                 # list all active tokens
warren token create <name>        # create a new token
warren token revoke <id>          # revoke a token by ID

Token names are labels to help you remember which machine each token belongs to (e.g. "laptop", "home-pc").

warren login

warren login [--api-url <url>]

Prompts for email and password. If no account exists, it registers one automatically. Credentials are saved to ~/.warren/credentials.json.

warren status

warren status

Shows your current authentication status, email, and plan.

Self-Hosting: warren-server

Run your own relay server. The warren-server binary is a single binary that needs no external dependencies.

warren-server \
  --bind 0.0.0.0:7000 \
  --auth-url http://localhost:8080 \
  --internal-secret your-secret \
  --cert /path/to/cert.pem \
  --key /path/to/key.pem

Or use static tokens in a TOML config (no warren-auth needed):

# /etc/warren-server.toml
[tokens]
mytoken123 = "alice"
anothertoken = "bob"

warren-server --config /etc/warren-server.toml

Self-Hosting: warren-auth

The SaaS auth API. Manages user accounts, JWT sessions, tunnel tokens, and Polar.sh billing webhooks.

warren-auth \
  --jwt-secret $(openssl rand -hex 32) \
  --internal-secret your-internal-secret \
  --polar-webhook-secret your-polar-secret \
  --base-url https://api.yourdomain.com

Environment variables are preferred in production:

WARREN_JWT_SECRET=...
WARREN_INTERNAL_SECRET=...
POLAR_WEBHOOK_SECRET=...
WARREN_BASE_URL=https://api.yourdomain.com
WARREN_DB=/var/lib/warren/warren.db

Deploy guide (Oracle Free Tier)

Warren ships with a complete deploy script for Oracle Cloud AMD64 VMs.

# On your Oracle VM:
unzip warren-v0.3.zip
cd warren
cargo build --release
sudo bash deploy/install.sh

The install script creates the warren system user, installs binaries, configures systemd units, sets up Caddy as a reverse proxy, and opens required firewall ports (80, 443, 7000).

Plans & Limits

Protocol

Warren uses a custom binary protocol (warren-proto) over QUIC streams.

• Hello — client sends version, client_id, tunnel token, and requested ports
• Reply — server replies Ok or Err with reason
• StreamOpen — server opens a new bidirectional QUIC stream for each incoming TCP connection, sends target port
• UdpHeader — 11-byte header prepended to QUIC datagrams for UDP forwarding (port + peer IP + peer port)

All messages are length-prefixed (4-byte LE u32) + MessagePack encoded. The ALPN identifier is warren/1.