rustunnel
Self-hosted, secure tunnel server in Rust. Expose local HTTP/HTTPS/TCP/UDP services to the public internet via TLS-encrypted WebSocket. Open-source, pay-as-you-go managed option, MCP server for AI agents.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/joaoh82--rustunnel)HTML
<a href="/listings/joaoh82--rustunnel"><img src="/api/listings/joaoh82--rustunnel/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Once you have a token, run the setup wizard:
rustunnel setup # Region [auto / eu / us / ap / self-hosted] (default: auto): (press Enter) # Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms # Server set to: eu.edge.rustunnel.com:4040 # Auth token: <paste your token>
Then expose a local service:
# HTTP tunnel — auto-selects the nearest region rustunnel http 3000 # Connect to a specific region rustunnel http 3000 --region eu # Custom subdomain rustunnel http 3000 --subdomain myapp # TCP tunnel — e.g. expose a local database rustunnel tcp 5432 # UDP tunnel — e.g. expose a game server rustunnel udp 27015 # P2P tunnel — expose a service to another rustunnel client rustunnel p2p 27015 --name my-game --secret "shared-secret" # P2P tunnel — connect to a peer's service rustunnel p2p 8000 --target my-game --secret "shared-secret"
The client prints the public URL as soon as the tunnel is established:
Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms ✓ tunnel open https://abc123.eu.edge.rustunnel.com
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 1,174 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # rustunnel
- [](https://github.com/joaoh82/rustunnel/actions/workflows/ci.yml)
- [](LICENSE)
- [](https://www.rust-lang.org)
- [](https://skillselion.com/mcp/tool/io.github.joaoh82/rustunnel)
- 
- The open-source tunnel that scales with you. Don't pay for idle time. Secure, Rust-fast, and Pay-as-you-go.
- Expose local services through a public server over encrypted WebSocket connections with TLS termination, HTTP/TCP proxying, a live dashboard, Prometheus metrics, and audit logging.
- You can self-host or use our managed service.
- **Using an AI agent?** rustunnel ships an [MCP server](https://rustunnel.com/docs/guides/mcp-server): one-click setup for Cursor (then add your [API token](https://rustunnel.com)):
- [](https://cursor.com/install-mcp?name=rustunnel&config=eyJjb21tYW5kIjoicnVzdHVubmVsLW1jcCIsImFyZ3MiOlsiLS1zZXJ2ZXIiLCJldS5lZGdlLnJ1c3R1bm5lbC5jb206NDA0MCIsIi0tYXBpIiwiaHR0cHM6Ly9ldS5lZGdlLnJ1c3R1bm5lbC5jb206ODQ0MyJdLCJlbnYiOnsiUlVTVFVOTkVMX1RPS0VOIjoiWU9VUl9UT0tFTiJ9fQ==)
- For Claude Code, Claude Desktop, Windsurf, and others, see the [agent integration guide](https://rustunnel.com/docs/guides/agent-integration) or the agent manual at [rustunnel.com/agents.md](https://rustunnel.com/agents.md).
- ---
- ## Table of Contents
- - [Hosted service](#hosted-service)
- - [Architecture overview](#architecture-overview)
- - [Requirements](#requirements)
- - [Local development setup](#local-development-setup)
- - [Build](#build)
- - [Run tests](#run-tests)
- - [Run the server locally](#run-the-server-locally)
- - [Run the client locally](#run-the-client-locally)
- - [Git hooks](#git-hooks)
- - [Production deployment (Ubuntu / systemd)](#production-deployment-ubuntu--systemd)
- - [1: Install dependencies](#1-install-dependencies)
- - [2: Build release binaries](#2-build-release-binaries)
- - [3: Create system user and directories](#3-create-system-user-and-directories)
- - [4: Install the server binary](#4-install-the-server-binary)
- - [5: Create the server config file](#5-create-the-server-config-file)
- - [6: TLS certificates (Let's Encrypt + Cloudflare)](#6-tls-certificates-lets-encrypt--cloudflare)
- - [7: Set up systemd service](#7-set-up-systemd-service)
- - [8: Open firewall ports](#8-open-firewall-ports)
- - [9: Verify the server is running](#9-verify-the-server-is-running)
- - [Updating the server](#updating-the-server)
- - [Docker deployment](#docker-deployment) · [full guide](docs/docker-deployment.md)
- - [Client configuration](#client-configuration)
- - [Installation](#installation)
- - [Setup wizard](#setup-wizard)
- - [Quick start (CLI flags)](#quick-start-cli-flags)
- - [Machine-readable output (`--json`)](#machine-readable-output---json)
- - [Config file](#config-file)
- - [Token management](#token-management)
- - [Port reference](#port-reference)
- - [Config file reference (server)](#config-file-reference-server)
- - [REST API](#rest-api)
- - [AI agent integration (MCP server)](#ai-agent-integration-mcp-server)
- - [OpenClaw skill](#openclaw-skill)
- - [Monitoring](#monitoring)
- - [Roadmap](#roadmap)
- - [Contributing](#contributing)
- - [License](#license)
- - [Contact](#contact)
- ---
- ## Hosted service
- You can use rustunnel without running your own server. We operate a global fleet of public edge servers that you can connect to immediately.
- ### Available regions
- | Region ID | Server | Location | Control plane | Status |
- |-----------|--------|----------|---------------|--------|
- | `eu` | `eu.edge.rustunnel.com` | Helsinki, FI | `:4040` | Live |
- | `us` | `us.edge.rustunnel.com` | Hillsboro, OR | `:4040` | Live |
- | `ap` | `ap.edge.rustunnel.com` | Singapore | `:4040` | Live |
- The client auto-selects the nearest region by default. Use `--region <id>` to connect to a specific one. The legacy address `edge.rustunnel.com` is a CNAME to `eu.edge.rustunnel.com` and will continue to work for backward compatibility.
- ### Getting an auth token
- Sign up for a free account at **[rustunnel.com](https://rustunnel.com)**. No waiting list, no manual approval.
- 1. Create an account at [rustunnel.com](https://rustunnel.com)
- 2. Go to **Dashboard → API Keys** and create a token
- 3. Copy the token. It is shown only once
- **Plans:**
- | Plan | Price | Tunnels | Subdomains | Bandwidth | TLS/HTTPS |
- |------|-------|---------|------------|-----------|-----------|
- | Hobby (free) | $0 | 2 concurrent | Random only | 1 GB/mo | ✓ |
- | Pay-as-you-go | $3/mo minimum, credited at $0.10/GB | No cap | Custom | $0.10/GB | ✓ |
- | Self-host | Free (run your own server) | Unlimited | Custom | Unmetered | ✓ |
- The Hobby (free) plan is a great way to get started: 2 concurrent tunnels, random subdomains only, and 1 GB/mo. Upgrade to pay-as-you-go from your dashboard whenever you need custom subdomains or more tunnels. Pay-as-you-go has no tunnel cap.
- ### Quick start with the hosted server
- Once you have a token, run the setup wizard:
- ```bash
- rustunnel setup
- # Region [auto / eu / us / ap / self-hosted] (default: auto): (press Enter)
- # Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
- # Server set to: eu.edge.rustunnel.com:4040
- # Auth token: <paste your token>
- ```
- Then expose a local service:
- ```bash
- # HTTP tunnel: auto-selects the nearest region
- rustunnel http 3000
- # Connect to a specific region
- rustunnel http 3000 --region eu
- # Custom subdomain
- rustunnel http 3000 --subdomain myapp
- # TCP tunnel: e.g. expose a local database
- rustunnel tcp 5432
- # UDP tunnel: e.g. expose a game server
- rustunnel udp 27015
- # P2P tunnel: expose a service to another rustunnel client
- rustunnel p2p 27015 --name my-game --secret "shared-secret"
- # P2P tunnel: connect to a peer's service
- rustunnel p2p 8000 --target my-game --secret "shared-secret"
- ```
- The client prints the public URL as soon as the tunnel is established:
- ```
- Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms
- ✓ tunnel open https://abc123.eu.edge.rustunnel.com
- ```
- ---
- ## Architecture overview
- 
- ```
- ┌──────────────────────────────────────────┐
- │ rustunnel-server │
- │ │
- Internet ──── :80 ─────▶│ HTTP edge (301 → HTTPS) │
- Internet ──── :443 ────▶│ HTTPS edge ──▶ yamux stream ──▶ client │
- Client ───── :4040 ────▶│ Control-plane WebSocket (TLS) │
- Browser ──── :8443 ────▶│ Dashboard UI + REST API │
- Prometheus ─ :9090 ────▶│ Metrics endpoint │
- Internet ── :20000+ ───▶│ TCP tunnel ports (one per TCP tunnel) │
- └──────────────────────────────────────────┘
- │ yamux multiplexed streams
- ▼
- ┌─────────────────────┐
- │ rustunnel client │
- │ (developer laptop) │
- └──────────┬──────────┘
- │ localhost
- ▼
- ┌────────────────┐
- │ local service │
- │ e.g. :3000 │
- └────────────────┘
- ```
- ---
- ## Requirements
- ### To build
- | Requirement | Version | Notes |
- |---|---|---|
- | Rust toolchain | 1.76+ | Install via [rustup](https://rustup.rs) |
- | `pkg-config` | any | Needed by `reqwest` (TLS) |
- | `libssl-dev` | any | On Debian/Ubuntu: `apt install libssl-dev` |
- | Node.js + npm | 18+ | Only needed to rebuild the dashboard UI |
- ### To run the server in production
- | Requirement | Notes |
- |---|---|
- | Linux (Ubuntu 22.04+) | systemd service included |
- | TLS certificate + private key | PEM format (Let's Encrypt recommended) |
- | Public IP / DNS | Wildcard DNS `*.tunnel.yourdomain.com → server IP` required for HTTP tunnels |
- ---
- ## Local development setup
- ### Build
- ```bash
- # Clone the repository
- git clone https://github.com/joaoh82/rustunnel.git
- cd rustunnel
- # Compile all workspace crates (debug mode)
- cargo build --workspace
- # Or use the Makefile shortcut
- make build
- ```
- ### Run tests
- The integration test suite spins up a real server on random ports and exercises auth, HTTP tunnels, TCP tunnels, and reconnection logic. It requires a running PostgreSQL instance.
- ```bash
- # Start the local PostgreSQL container (once per machine, persists across reboots)
- make db-start
- # Full suite (unit + integration)
- make test
- # With output visible
- TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test \
- cargo test --workspace -- --nocapture
- # Stop PostgreSQL when you no longer need it
- make db-stop
- ```
- `make db-start` runs `deploy/docker-compose.dev-deps.yml` which starts a Postgres 16 container on `localhost:5432`. The `make test` target injects `TEST_DATABASE_URL` automatically. If you run `cargo test` directly, export the variable first:
- ```bash
- export TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test
- ```
- ### Run the server locally
- Generate a self-signed certificate for local testing:
- ```bash
- mkdir -p /tmp/rustunnel-dev
- openssl req -x509 -newkey rsa:2048 -keyout /tmp/rustunnel-dev/key.pem \
- -out /tmp/rustunnel-dev/cert.pem -days 365 -nodes \
- -subj "/CN=localhost"
- ```
- A ready-made local config is checked into the repository at **`deploy/local/server.toml`**.
- It points to the self-signed cert paths above and has auth disabled for convenience.
- Start the server with it directly:
- ```bash
- cargo run -p rustunnel-server -- --config deploy/local/server.toml
- ```
- Key settings in `deploy/local/server.toml`:
- | Setting | Value |
- |---|---|
- | Domain | `localhost` |
- | HTTP edge | `:8080` |
- | HTTPS edge | `:8443` |
- | Control plane | `:4040` |
- | Dashboard | `:4041` |
- | Auth token | `dev-secret-change-me` |
- | Auth required | `false` |
- | TLS cert | `/tmp/rustunnel-dev/cert.pem` |
- | TLS key | `/tmp/rustunnel-dev/key.pem` |
- | Database | `/tmp/rustunnel-dev/rustunnel.db` |
- ### Run the client locally
- With the server running, expose a local service (e.g. something on port 3000):
- ```bash
- # HTTP tunnel
- cargo run -p rustunnel-client -- http 3000 \
- --server localhost:4040 \
- --token dev-secret-change-me \
- --insecure
- # TCP tunnel
- cargo run -p rustunnel-client -- tcp 5432 \
- --server localhost:4040 \
- --token dev-secret-change-me \
- --insecure
- ```
- > `--insecure` skips TLS certificate verification. Required when using a
- > self-signed certificate locally. Never use this flag against a production server.
- The client will print a public URL, for example:
- ```
- http tunnel → http://abc123.localhost:8080
- tcp tunnel → tcp://localhost:20000
- ```
- ### Testing the HTTP tunnel locally
- The tunnel URL uses a subdomain (e.g. `http://abc123.localhost:8080`).
- Browsers won't resolve `*.localhost` subdomains by default, so you have two options:
- **Option A: curl with a Host header (no setup required)**
- ```bash
- curl -v -H "Host: abc123.localhost" http://localhost:8080/
- ```
- **Option B: wildcard DNS via dnsmasq (enables browser access)**
- ```bash
- # Install and configure dnsmasq to resolve *.localhost → 127.0.0.1
- brew install dnsmasq
- echo "address=/.localhost/127.0.0.1" | sudo tee -a $(brew --prefix)/etc/dnsmasq.conf
- sudo brew services start dnsmasq
- # Tell macOS to use dnsmasq for .localhost queries
- sudo mkdir -p /etc/resolver
- echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/localhost
- ```
- Then visit `http://abc123.localhost:8080` in the browser (include `:8080` since the
- local config uses port 8080, not port 80).
- ### Git hooks
- A pre-push hook is included in `.githooks/` that mirrors the CI check step
- (format check + Clippy). Run this once after cloning to activate it:
- ```bash
- make install-hooks
- ```
- From that point on, every `git push` will automatically run:
- ```bash
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
- ```
- If either check fails the push is aborted, keeping the remote branch green.
- ---
- ## Production deployment (Ubuntu / systemd)
- The steps below match a deployment where:
- - Domain: `edge.rustunnel.com`
- - Wildcard DNS: `*.edge.rustunnel.com → <server IP>`
- - TLS certs: Let's Encrypt via Certbot + Cloudflare DNS challenge
- ### 1: Install dependencies
- ```bash
- apt update && apt install -y \
- pkg-config libssl-dev curl git \
- certbot python3-certbot-dns-cloudflare
- ```
- Install Rust (as the build user, not root):
- ```bash
- curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
- source "$HOME/.cargo/env"
- ```
- ### 2: Build release binaries
- ```bash
- git clone https://github.com/joaoh82/rustunnel.git
- cd rustunnel
- cargo build --release -p rustunnel-server -p rustunnel-client
- ```
- Binaries will be at:
- - `target/release/rustunnel-server`
- - `target/release/rustunnel`
- ### 3: Create system user and directories
- ```bash
- useradd --system --no-create-home --shell /usr/sbin/nologin rustunnel
- mkdir -p /etc/rustunnel /var/lib/rustunnel
- chown rustunnel:rustunnel /var/lib/rustunnel
- chmod 750 /var/lib/rustunnel
- ```
- ### 4: Install the server binary
- ```bash
- install -Dm755 target/release/rustunnel-server /usr/local/bin/rustunnel-server
- # Optionally install the client system-wide
- install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel
- ```
- Or use the Makefile target (runs build + install + systemd setup):
- ```bash
- sudo make deploy
- ```
- ### 5: Set up PostgreSQL
- rustunnel requires PostgreSQL for shared state (tokens, tunnel history, audit log).
- ```bash
- apt install -y postgresql postgresql-contrib
- # Start and enable the service
- systemctl enable --now postgresql
- ```
- Create a dedicated database and user:
- ```bash
- sudo -u postgres psql <<'SQL'
- CREATE USER rustunnel WITH PASSWORD 'CHANGE_ME';
- CREATE DATABASE rustunnel OWNER rustunnel;
- GRANT ALL PRIVILEGES ON DATABASE rustunnel TO rustunnel;
- SQL
- ```
- > **Tip:** For managed PostgreSQL (e.g. AWS RDS, DigitalOcean Managed Database, Supabase) skip the
- > `apt install` step above and just note the connection URL for the config in the next step.
- Schema migrations run automatically when the server starts. No manual SQL needed.
- ### 6: Create the server config file
- Create `/etc/rustunnel/server.toml` with the content below.
- Replace `your-admin-token-here` with a strong random secret (e.g. `openssl rand -hex 32`).
- ```toml
- # /etc/rustunnel/server.toml
- [server]
- # Primary domain: must match your wildcard DNS record.
- domain = "edge.rustunnel.com"
- # Ports for incoming tunnel traffic (requires CAP_NET_BIND_SERVICE or root).
- http_port = 80
- https_port = 443
- # Control-plane WebSocket port: clients connect here.
- control_port = 4040
- # Dashboard UI and REST API port.
- dashboard_port = 8443
- # Allowed CORS origin for the dashboard UI.
- # Set to the URL where you serve the dashboard-ui (e.g. http://localhost:3000 for local dev).
- dashboard_origin = "http://localhost:3000"
- # ── TLS ─────────────────────────────────────────────────────────────────────
- [tls]
- # Paths written by Certbot (see step 6).
- cert_path = "/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem"
- key_path = "/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem"
- # Set acme_enabled = true only if you want rustunnel to manage certs itself
- # via the ACME protocol (requires Cloudflare credentials below).
- # When using Certbot (recommended), leave this false.
- acme_enabled = false
- # ── Auth ─────────────────────────────────────────────────────────────────────
- [auth]
- # Strong random secret: used both as the admin token and for client auth.
- # Generate: openssl rand -hex 32
- admin_token = "your-admin-token-here"
- require_auth = true
- # Failed auth attempts per source IP per minute before rejection (0 = off).
- max_failed_auth_per_minute = 10
- # ── Database ─────────────────────────────────────────────────────────────────
- [database]
- # PostgreSQL connection URL: the database and user must exist before starting
- # the server (see the PostgreSQL setup step above). Schema migrations run
- # automatically on first start.
- url = "postgresql://rustunnel:CHANGE_ME@localhost:5432/rustunnel"
- # Per-region SQLite file for captured HTTP request bodies.
- # The directory must be writable by the rustunnel user.
- captured_path = "/var/lib/rustunnel/captured.db"
- # ── Logging ──────────────────────────────────────────────────────────────────
- [logging]
- level = "info"
- format = "json"
- # Optional: write an append-only audit log (JSON-lines) for auth attempts,
- # tunnel registrations, token creation/deletion, and admin actions.
- # Omit or comment out to disable.
- audit_log_path = "/var/lib/rustunnel/audit.log"
- # ── Limits ───────────────────────────────────────────────────────────────────
- [limits]
- # Maximum tunnels a single authenticated session may register.
- max_tunnels_per_session = 10
- # Maximum simultaneous proxied connections per tunnel (semaphore).
- max_connections_per_tunnel = 100
- # Per-tunnel request rate limit (requests/second).
- rate_limit_rps = 100
- # Per-source-IP rate limit (requests/second). Set to 0 to disable.
- ip_rate_limit_rps = 100
- # Maximum size of a proxied HTTP request body (bytes). Default: 10 MB.
- request_body_max_bytes = 10485760
- # Inclusive port range reserved for TCP tunnels.
- # Each active TCP tunnel consumes one port from this range.
- tcp_port_range = [20000, 20099]
- # Inclusive port range reserved for UDP tunnels.
- # Each active UDP tunnel consumes one port from this range.
- # Must not overlap with tcp_port_range. Set to [0, 0] to disable UDP tunnels.
- udp_port_range = [20100, 20199]
- ```
- Secure the file:
- ```bash
- chown root:rustunnel /etc/rustunnel/server.toml
- chmod 640 /etc/rustunnel/server.toml
- ```
- ### 7: TLS certificates (Let's Encrypt + Cloudflare)
- Create the Cloudflare credentials file:
- ```bash
- cat > /etc/letsencrypt/cloudflare.ini <<'EOF'
- # Cloudflare API token with DNS:Edit permission for the zone.
- dns_cloudflare_api_token = YOUR_CLOUDFLARE_API_TOKEN
- EOF
- chmod 600 /etc/letsencrypt/cloudflare.ini
- ```
- Request a certificate covering the bare domain and the wildcard (required for HTTP subdomain tunnels):
- ```bash
- certbot certonly \
- --dns-cloudflare \
- --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
- -d "edge.rustunnel.com" \
- -d "*.edge.rustunnel.com" \
- --agree-tos \
- --email your@email.com
- ```
- Certbot writes the certificate to:
- ```
- /etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem
- /etc/letsencrypt/live/edge.rustunnel.com/privkey.pem
- ```
- These paths are already set in the config above. Certbot sets up automatic renewal via a systemd timer.
- rustunnel reads TLS certificates from disk at startup, so it must be restarted after each renewal.
- Add a Certbot deploy hook to do this automatically:
- ```bash
- cat > /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh <<'EOF'
- #!/bin/sh
- systemctl restart rustunnel.service
- EOF
- chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-rustunnel.sh
- ```
- Allow the `rustunnel` service user to read the certificates:
- ```bash
- # Grant read access to the live/ and archive/ directories
- chmod 755 /etc/letsencrypt/{live,archive}
- chmod 640 /etc/letsencrypt/live/edge.rustunnel.com/*.pem
- chgrp rustunnel /etc/letsencrypt/live/edge.rustunnel.com/*.pem
- chgrp rustunnel /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
- chmod 640 /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
- ```
- ### 8: Set up systemd service
- ```bash
- # Copy the unit file from the repository
- install -Dm644 deploy/rustunnel.service /etc/systemd/system/rustunnel.service
- systemctl daemon-reload
- systemctl enable --now rustunnel.service
- # Check it started
- systemctl status rustunnel.service
- journalctl -u rustunnel.service -f
- ```
- ### 9: Open firewall ports
- ```bash
- ufw allow 80/tcp comment "rustunnel HTTP edge"
- ufw allow 443/tcp comment "rustunnel HTTPS edge"
- ufw allow 4040/tcp comment "rustunnel control plane"
- ufw allow 8443/tcp comment "rustunnel dashboard"
- ufw allow 9090/tcp comment "rustunnel Prometheus metrics"
- # TCP tunnel port range (must match tcp_port_range in server.toml)
- ufw allow 20000:20099/tcp comment "rustunnel TCP tunnels"
- # UDP tunnel port range (must match udp_port_range in server.toml)
- ufw allow 20100:20199/udp comment "rustunnel UDP tunnels"
- ```
- ### 10: Verify the server is running
- ```bash
- # Health check: use dashboard_port from server.toml (default 8443 in production)
- curl http://localhost:8443/api/status
- # Confirm which ports the process is actually bound to
- ss -tlnp | grep rustunnel-serve
- # Startup banner is visible in the logs
- journalctl -u rustunnel.service --no-pager | tail -30
- # Prometheus metrics
- curl -s http://localhost:9090/metrics
- ```
- > **Port reminder**: port 4040 is the control-plane WebSocket (clients connect here),
- > not the dashboard. Hitting it with plain HTTP returns `HTTP/0.9` which is expected.
- > The dashboard is on `dashboard_port`. Check your `server.toml` if unsure.
- ### Updating the server
- Pull the latest code, rebuild, install, and restart in one command:
- ```bash
- cd ~/rustunnel && sudo make update-server
- ```
- This runs `git pull` → `cargo build --release` → `install` → `systemctl restart` → `systemctl status`.
- ---
- ## Docker deployment
- A full Docker guide covering both local development (self-signed cert) and
- production VPS (Let's Encrypt) is available in
- [**docs/docker-deployment.md**](docs/docker-deployment.md).
- ### Pull the published image
- Multi-arch images (`linux/amd64` + `linux/arm64`) are published to GitHub
- Container Registry on every stable release. No build required:
- ```bash
- # Latest stable, or pin a version (e.g. :0.8.1)
- docker pull ghcr.io/joaoh82/rustunnel-server:latest
- # Run it with your server config mounted at /etc/rustunnel/server.toml
- docker run --rm \
- -p 80:80 -p 443:443 -p 4040:4040 -p 8443:8443 \
- -v "$PWD/deploy/server.toml:/etc/rustunnel/server.toml:ro" \
- ghcr.io/joaoh82/rustunnel-server:latest
- ```
- ### Quick reference (build from source)
- ```bash
- # Build the image locally (includes Next.js dashboard + Rust server)
- make docker-build
- # Build and push a multi-arch image to GHCR (maintainers; needs buildx + ghcr login)
- make docker-push
- # Local development (self-signed cert, no auth required)
- docker compose -f deploy/docker-compose.local.yml up
- # Production VPS (requires deploy/server.toml to be configured first)
- make docker-run
- # Production + Prometheus + Grafana monitoring stack
- make docker-run-monitoring
- # Tail server logs
- make docker-logs
- # Stop everything
- make docker-stop
- ```
- ### Files
- | File | Purpose |
- |------|---------|
- | `deploy/Dockerfile` | Multi-stage build: Node.js UI → Rust server → slim runtime |
- | `deploy/docker-compose.yml` | Production compose file |
- | `deploy/docker-compose.local.yml` | Local development compose file |
- | `deploy/server.toml` | Production server config template |
- | `deploy/server.local.toml` | Local development server config |
- | `deploy/prometheus.yml` | Prometheus scrape config |
- ---
- ## Client configuration
- ### Installation
- **Option 1: Homebrew (macOS and Linux, recommended)**
- ```bash
- brew tap joaoh82/rustunnel
- brew install rustunnel
- ```
- Homebrew installs pre-built binaries. No Rust toolchain required.
- The formula is updated automatically on every release. This installs
- both `rustunnel` (the CLI client) and `rustunnel-mcp` (the MCP server
- for AI agent integration).
- **Option 2: Pre-built binary**
- Download the archive for your platform from the
- [latest GitHub Release](https://github.com/joaoh82/rustunnel/releases/latest),
- extract it, and move the `rustunnel` binary to a directory on your `$PATH`:
- ```bash
- # Example for macOS Apple Silicon
- curl -L https://github.com/joaoh82/rustunnel/releases/latest/download/rustunnel-<version>-aarch64-apple-darwin.tar.gz \
- | tar xz
- sudo install -Dm755 rustunnel /usr/local/bin/rustunnel
- ```
- Available targets:
- | Platform | Archive |
- |----------|---------|
- | macOS Apple Silicon | `rustunnel-<version>-aarch64-apple-darwin.tar.gz` |
- | macOS Intel | `rustunnel-<version>-x86_64-apple-darwin.tar.gz` |
- | Linux x86_64 (glibc) | `rustunnel-<version>-x86_64-unknown-linux-gnu.tar.gz` |
- | Linux x86_64 (musl, static) | `rustunnel-<version>-x86_64-unknown-linux-musl.tar.gz` |
- | Linux arm64 | `rustunnel-<version>-aarch64-unknown-linux-gnu.tar.gz` |
- | Windows x86_64 | `rustunnel-<version>-x86_64-pc-windows-msvc.zip` |
- **Option 3: Build from source**
- Requires Rust 1.76+.
- ```bash
- git clone https://github.com/joaoh82/rustunnel.git
- cd rustunnel
- cargo build --release -p rustunnel-client
- sudo install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel
- # Or via make
- make deploy-client
- ```
- ### Setup wizard
- The easiest way to create your config file is the interactive setup wizard:
- ```bash
- rustunnel setup
- ```
- It prompts for your region and auth token, then writes `~/.rustunnel/config.yml` with the correct server address and a commented `tunnels:` example section.
- ```
- rustunnel setup: create ~/.rustunnel/config.yml
- Region [auto / eu / us / ap / self-hosted] (default: auto):
- Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
- Server set to: eu.edge.rustunnel.com:4040
- Auth token (leave blank to skip): rt_live_abc123...
- Created: /Users/you/.rustunnel/config.yml
- Run `rustunnel start` to connect using this config.
- ```
- Pick a specific region (`eu`, `us`, `ap`) to connect directly, or `auto` (the default) to let the client probe all regions and pick the nearest. Choose `self-hosted` if you run your own server. The wizard will then prompt for your server address.
- After running setup, use `rustunnel start` to connect with all tunnels defined in the config, or use `rustunnel http <port>` / `rustunnel tcp <port>` for one-off tunnels.
- ### Quick start (CLI flags)
- ```bash
- # Expose a local HTTP service on port 3000 (auto-selects nearest region)
- rustunnel http 3000 \
- --token YOUR_AUTH_TOKEN
- # Connect to a specific region
- rustunnel http 3000 --region eu --token YOUR_AUTH_TOKEN
- # Use an explicit server address (bypasses region selection)
- rustunnel http 3000 \
- --server edge.rustunnel.com:4040 \
- --token YOUR_AUTH_TOKEN
- # Expose a local service with a custom subdomain
- rustunnel http 3000 \
- --token YOUR_AUTH_TOKEN \
- --subdomain myapp
- # Expose a local TCP service (e.g. a PostgreSQL database)
- rustunnel tcp 5432 \
- --token YOUR_AUTH_TOKEN
- # Disable automatic reconnection
- rustunnel http 3000 --no-reconnect
- ```
- ### Machine-readable output (`--json`)
- All tunnel-running commands (`http`, `tcp`, `udp`, `p2p`, `start`) and
- `token create` accept a `--json` flag. With it, stdout emits NDJSON,
- one JSON event object per line, instead of the human-readable startup
- box, which makes the CLI easy to drive from scripts and AI agents:
- ```bash
- rustunnel http 3000 --json --token YOUR_AUTH_TOKEN
- ```
- ```json
- {"event":"tunnel_ready","protocol":"http","public_url":"https://myapp.eu.edge.rustunnel.com","local_port":3000,"local_host":"localhost","tunnel_id":"6f9a…","name":"myapp"}
- ```
- Events:
- | Event | When | Fields |
- |-------|------|--------|
- | `tunnel_ready` | Tunnel registered and accepting traffic | `protocol`, `public_url`, `public_addr` (host:port, tcp/udp only), `local_port`, `local_host`, `tunnel_id`, `name` |
- | `reconnecting` | Connection dropped, retry scheduled | `attempt`, `reason`, `delay_secs` |
- | `reconnected` | Reconnect succeeded (fresh `tunnel_ready` events follow) | None |
- | `error` | Fatal error; process exits with code 1 | `code` (`config`/`auth`/`tunnel`/`connection`/`protocol`/`io`), `message`, `hint` |
- | `token_created` | `token create --json` succeeded | `token`, `name`, `id` |
- Diagnostics still go to stderr, so stdout stays valid NDJSON. For the
- `http`, `tcp`, `udp`, and `p2p` commands the auth token can also be
- supplied via the `RUSTUNNEL_TOKEN` environment variable instead of
- `--token` (`start` reads tokens from the config file).
- ### Config file
- Default location: `~/.rustunnel/config.yml`
- ```yaml
- # ~/.rustunnel/config.yml
- # Tunnel server address (host:control_port)
- server: edge.rustunnel.com:4040
- # Auth token (from server admin_token or a token created via the dashboard)
- auth_token: YOUR_AUTH_TOKEN
- # Region preference: auto (probe & pick nearest), or eu / us / ap.
- # Omit for self-hosted / single-server setups.
- region: auto
- # Named tunnels started with `rustunnel start`
- tunnels:
- web:
- proto: http
- local_port: 3000
- subdomain: myapp # optional: server assigns one if omitted
- db:
- proto: tcp
- local_port: 5432
- ```
- Start all tunnels from the config file:
- ```bash
- rustunnel start
- # or with an explicit path
- rustunnel start --config /path/to/config.yml
- ```
- ### Token management
- **Hosted service:** manage tokens from the [rustunnel.com](https://rustunnel.com) dashboard under **Dashboard → API Keys**. You can create, label, and revoke tokens without any CLI commands.
- **Self-hosted:** create additional tokens via the dashboard API:
- ```bash
- rustunnel token create \
- --name "ci-deploy" \
- --server your-server:8443 \
- --admin-token YOUR_ADMIN_TOKEN
- ```
- Or via `curl`:
- ```bash
- curl -s -X POST https://your-server:8443/api/tokens \
- -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"label": "ci-deploy"}'
- ```
- ---
- ## Port reference
- | Port | Protocol | Purpose |
- |------|----------|---------|
- | 80 | TCP | HTTP edge: redirects to HTTPS; also ACME HTTP-01 challenge |
- | 443 | TCP | HTTPS edge: TLS-terminated tunnel ingress |
- | 4040 | TCP | Control-plane WebSocket: clients connect here |
- | 8443 | TCP | Dashboard UI and REST API |
- | 9090 | TCP | Prometheus metrics (`/metrics`) |
- | 20000–20099 | TCP | TCP tunnel range (configurable via `tcp_port_range`) |
- | 20100–20199 | UDP | UDP tunnel range (configurable via `udp_port_range`) |
- ---
- ## Config file reference (server)
- | Key | Type | Default | Description |
- |-----|------|---------|-------------|
- | `server.domain` | string | None | Base domain for tunnel URLs |
- | `server.http_port` | u16 | None | HTTP edge port |
- | `server.https_port` | u16 | None | HTTPS edge port |
- | `server.control_port` | u16 | None | WebSocket control-plane port |
- | `server.dashboard_port` | u16 | `4040` | Dashboard port |
- | `tls.cert_path` | string | None | Path to TLS certificate (PEM) |
- | `tls.key_path` | string | None | Path to TLS private key (PEM) |
- | `tls.acme_enabled` | bool | `false` | Enable built-in ACME renewal |
- | `tls.acme_email` | string | `""` | Contact email for ACME |
- | `tls.acme_staging` | bool | `false` | Use Let's Encrypt staging CA |
- | `tls.acme_account_dir` | string | `/var/lib/rustunnel` | ACME state directory |
- | `tls.cloudflare_api_token` | string | `""` | Cloudflare DNS API token (prefer env var `CLOUDFLARE_API_TOKEN`) |
- | `tls.cloudflare_zone_id` | string | `""` | Cloudflare Zone ID (prefer env var `CLOUDFLARE_ZONE_ID`) |
- | `auth.admin_token` | string | None | Master auth token |
- | `auth.require_auth` | bool | None | Reject unauthenticated clients |
- | `auth.max_failed_auth_per_minute` | int | `10` | Failed auth attempts allowed per source IP per minute before further attempts are rejected (control-plane handshake and dashboard API); `0` disables |
- | `database.url` | string | None | PostgreSQL connection URL (required) |
- | `database.captured_path` | string | `/var/lib/rustunnel/captured.db` | Per-region SQLite file for captured HTTP request bodies |
- | `server.dashboard_origin` | string | `""` | Allowed CORS origin for the dashboard UI (e.g. `http://localhost:3000`) |
- | `logging.level` | string | None | `trace` / `debug` / `info` / `warn` / `error` |
- | `logging.format` | string | None | `json` or `pretty` |
- | `logging.audit_log_path` | string | `null` | Path for audit log (JSON-lines); omit to disable |
- | `limits.max_tunnels_per_session` | usize | None | Max tunnels per connected client |
- | `limits.max_connections_per_tunnel` | usize | None | Max concurrent connections per tunnel |
- | `limits.rate_limit_rps` | u32 | None | Per-tunnel request rate cap (req/s) |
- | `limits.ip_rate_limit_rps` | u32 | `100` | Per-source-IP rate cap (req/s); `0` = disabled |
- | `limits.request_body_max_bytes` | usize | None | Max proxied request body size (bytes) |
- | `limits.tcp_port_range` | [u16, u16] | None | Inclusive `[low, high]` TCP tunnel port range |
- | `limits.udp_port_range` | [u16, u16] | `[0, 0]` | Inclusive `[low, high]` UDP tunnel port range; `[0, 0]` disables UDP tunnels |
- | `region.id` | string | `"default"` | Region identifier recorded in tunnel history (e.g. `"eu"`, `"us"`, `"ap"`) |
- | `region.name` | string | `"Default"` | Human-readable region name shown in the dashboard |
- | `region.location` | string | `""` | Physical location label (e.g. `"Helsinki, FI"`) |
- ---
- ## Monitoring
- A Prometheus metrics endpoint is available at `:9090/metrics`:
- ```
- rustunnel_active_sessions # gauge: connected clients
- rustunnel_active_tunnels_http # gauge: active HTTP tunnels
- rustunnel_active_tunnels_tcp # gauge: active TCP tunnels
- ```
- Start with the full monitoring stack (Prometheus + Grafana):
- ```bash
- make docker-run-monitoring
- # Grafana: http://localhost:3000 (admin / changeme)
- # Prometheus: http://localhost:9090
- ```
- > **Production note:** The default Grafana password is `changeme`. Set the `GRAFANA_PASSWORD` environment variable before starting the stack in production:
- > ```bash
- > export GRAFANA_PASSWORD=your-strong-password
- > make docker-run-monitoring
- > ```
- ---
- ## REST API
- The dashboard port exposes a REST API for programmatic access to tunnels, tokens, captured requests, and tunnel history. All endpoints (except the health check) require an `Authorization: Bearer <token>` header.
- `/api/tunnels`, `/api/groups`, and their per-tunnel sub-resources are scoped by caller: the admin token sees everything; a user-scoped API token sees only its own tunnels and groups; tunnels the caller can't see return `404`, never `403`. See [docs/api-reference.md § Visibility scope](docs/api-reference.md#visibility-scope) for the full rules.
- **Quick reference**
- | Method | Path | Description |
- |--------|------|-------------|
- | `GET` | `/api/status` | Health check (no auth) |
- | `GET` | `/api/tunnels` | List active tunnels |
- | `GET` | `/api/tunnels/:id` | Get a single tunnel |
- | `DELETE` | `/api/tunnels/:id` | Force-close a tunnel |
- | `GET` | `/api/tunnels/:id/requests` | Captured HTTP requests |
- | `POST` | `/api/tunnels/:id/replay/:req_id` | Fetch stored request for replay |
- | `GET` | `/api/tokens` | List API tokens |
- | `POST` | `/api/tokens` | Create an API token |
- | `DELETE` | `/api/tokens/:id` | Delete an API token |
- | `GET` | `/api/history` | Paginated tunnel history |
- Full request/response schemas, query parameters, and examples are in
- [**docs/api-reference.md**](docs/api-reference.md).
- A machine-readable OpenAPI 3.0 spec is served at `GET /api/openapi.json` (no auth required).
- ---
- ## AI agent integration (MCP server)
- rustunnel ships a `rustunnel-mcp` binary that implements the
- [Model Context Protocol](https://spec.modelcontextprotocol.io) over stdio,
- letting AI agents (Claude, GPT-4o, custom agents) open and manage tunnels
- without any manual intervention.
- **Works with any MCP harness.** For copy-paste config for Claude Code, Claude
- Desktop, Codex, Cursor, Windsurf, Cline, and custom agents, plus a one-command
- installer, see the **[Agent Integration Guide](docs/agent-integration.md)**:
- ```bash
- ./integrations/install.sh # prompts for your token, writes the config
- ```
- ### Quick setup (Claude Desktop, hosted server)
- ```json
- {
- "mcpServers": {
- "rustunnel": {
- "command": "rustunnel-mcp",
- "args": [
- "--server", "edge.rustunnel.com:4040",
- "--api", "https://edge.rustunnel.com:8443"
- ],
- "env": { "RUSTUNNEL_TOKEN": "<your-token>" }
- }
- }
- }
- ```
- Set `RUSTUNNEL_TOKEN` once and the agent never has to pass a token on a tool call.
- ### Available tools
- | Tool | Description |
- |------|-------------|
- | `create_tunnel` | Open a tunnel and return the public URL: HTTP/TCP/UDP, P2P, and load-balanced pools with health checks |
- | `list_tunnels` | List all active tunnels |
- | `close_tunnel` | Force-close a tunnel by ID |
- | `list_regions` | List available server regions |
- | `get_connection_info` | Return the CLI command for cloud/sandbox agents |
- | `get_tunnel_history` | Retrieve past tunnel activity |
- ### Installation
- **Homebrew (macOS and Linux):** installs `rustunnel-mcp` alongside the CLI:
- ```bash
- brew tap joaoh82/rustunnel
- brew install rustunnel
- ```
- **Build from source:**
- ```bash
- make release-mcp
- sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp
- ```
- Full setup guide, configuration options, and workflow examples are in
- [**docs/mcp-server.md**](docs/mcp-server.md).
- ### Claude Code plugin
- The easiest way to use rustunnel with [Claude Code](https://claude.com/claude-code).
- Install the plugin and it handles all MCP configuration automatically. Just enter
- your token once and start asking Claude to expose ports.
- ```
- /plugin install rustunnel
- ```
- The plugin prompts for your server address and API token at enable time, stores
- them securely, and starts the MCP server in the background. No `.mcp.json` editing
- or manual setup needed.
- **Plugin directory:** [`plugins/claude-code/`](plugins/claude-code/)
- **Documentation:** [docs/claude-plugin.md](docs/claude-plugin.md)
- ### OpenClaw skill
- rustunnel ships an [OpenClaw](https://openclaw.dev) skill that gives any
- OpenClaw-compatible AI agent first-class knowledge of rustunnel: config file
- format, authentication, tool signatures, and common workflows, without you
- having to explain it.
- **Skill file:** [`skills/rustunnel/SKILL.md`](skills/rustunnel/SKILL.md)
- **What it covers:**
- | Topic | Details |
- |-------|---------|
- | Config file | Location (`~/.rustunnel/config.yml`), format, named tunnels |
- | First-time setup | `rustunnel setup` wizard or manual config creation |
- | MCP tools | `create_tunnel`, `list_tunnels`, `close_tunnel`, `get_connection_info`, `get_tunnel_history` |
- | Workflows | Webhook testing, demo sharing, cloud sandbox (no subprocess), named tunnels |
- | Security | Token handling, file permissions, HTTPS-only transport |
- **To load the skill in Claude Code:**
- ```bash
- /skills load skills/rustunnel/SKILL.md
- ```
- Once loaded, you can ask the agent things like:
- > "Expose my local port 3000 as an HTTPS tunnel using rustunnel."
- > "List my active tunnels and close the one forwarding port 5432."
- > "Set up my rustunnel config file with my token."
- The skill instructs the agent to read credentials from `~/.rustunnel/config.yml`
- automatically, so you won't be prompted for your token on every invocation.
- ---
- ## Roadmap
- A detailed list of shipped features and planned future work is maintained in
- [**docs/ROADMAP.md**](docs/ROADMAP.md).
- ---
- ## Contributing
- Contributions are welcome! Please follow these steps:
- 1. **Fork** the repository and create a feature branch from `main`.
- 2. Run `make install-hooks` once after cloning to activate the pre-push quality gate.
- 3. Make your changes. Ensure `make check` (fmt + Clippy) and `make test` pass locally.
- 4. Open a **Pull Request** with a clear description of what changed and why.
- 5. A maintainer will review and merge once CI is green.
- ### Guidelines
- - Keep PRs focused: one logical change per PR.
- - Add or update tests for any new behaviour.
- - Follow the existing code style; `cargo fmt` is enforced by CI.
- - For larger changes or new features, open an issue first to discuss the approach.
- ---
- ## License
- This project is licensed under the **GNU AGPLv3 License**. See the [LICENSE](LICENSE) file for details.
- ---
- ## Contact
- **João Henrique Machado Silva**
- - GitHub: [@joaoh82](https://github.com/joaoh82)
- - Project: [github.com/joaoh82/rustunnel](https://github.com/joaoh82/rustunnel)
- - Issues & feature requests: [GitHub Issues](https://github.com/joaoh82/rustunnel/issues)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.