Rustunnel

Requirements

1 — Install dependencies

apt update && apt install -y \
  pkg-config libssl-dev curl git \
  certbot python3-certbot-dns-cloudflare

Install Rust (as the build user, not root):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Ports for incoming tunnel traffic (requires CAP_NET_BIND_SERVICE or root).

http_port = 80 https_port = 443

via the ACME protocol (requires Cloudflare credentials below).

Production VPS (requires deploy/server.toml to be configured first)

make docker-run

To build

Local development setup

Build

```bash

Compile all workspace crates (debug mode)

cargo build --workspace

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

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

2 — Build release binaries

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

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):

the server (see the PostgreSQL setup step above). Schema migrations run

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.

Build the image (includes Next.js dashboard + Rust server)

make docker-build

Installation

Option 1 — Homebrew (macOS and Linux, recommended)

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, extract it, and move the rustunnel binary to a directory on your $PATH:

```bash

Setup wizard

The easiest way to create your config file is the interactive setup wizard:

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.

Omit for self-hosted / single-server setups.

region: auto

Quick setup (Claude Desktop — hosted server)

{
  "mcpServers": {
    "rustunnel": {
      "command": "rustunnel-mcp",
      "args": [
        "--server", "edge.rustunnel.com:4040",
        "--api",    "https://edge.rustunnel.com:8443"
      ]
    }
  }
}

Installation

Homebrew (macOS and Linux) — installs rustunnel-mcp alongside the CLI:

brew tap joaoh82/rustunnel
brew install rustunnel

Build from source:

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.

Quick start with the hosted server

Once you have a token, run the setup wizard:

```bash rustunnel setup

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+.

Quick start (CLI flags)

```bash

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.

---

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

Optional: write an append-only audit log (JSON-lines) for auth attempts,

Client configuration

Config file

Default location: ~/.rustunnel/config.yml

```yaml

~/.rustunnel/config.yml

Config file reference (server)

---

Dashboard UI and REST API port.

dashboard_port = 8443

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):

Certbot writes the certificate to:

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:

Allow the `rustunnel` service user to read the certificates:

Quick reference

```bash

Region preference: auto (probe & pick nearest), or eu / us / ap.

Port reference

---

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 for the full rules.

Quick reference

Full request/response schemas, query parameters, and examples are in docs/api-reference.md.

A machine-readable OpenAPI 3.0 spec is served at GET /api/openapi.json (no auth required).

---

Full suite (unit + integration)

make test

AI agent integration (MCP server)

rustunnel ships a rustunnel-mcp binary that implements the Model Context Protocol over stdio, letting AI agents (Claude, GPT-4o, custom agents) open and manage tunnels without any manual intervention.

Claude Code plugin

The easiest way to use rustunnel with 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/ Documentation: docs/claude-plugin.md