rustunnel

https://rustunnel.com/docs
Admin
rustunnel is an open-source secure tunnel server written in Rust that exposes localhost over...
Tokens:32,398
Snippets:405
Trust Score:3.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Rustunnel Quick Start Guide

Source: https://rustunnel.com/docs/guides/client-guide

A quick guide to setting up and using rustunnel. This involves getting an auth token, creating a configuration file interactively, and then exposing local services via HTTP or TCP.

```bash
# 1. Get an auth token
#    → Sign up at https://rustunnel.com, then go to Dashboard → API Keys → Create token

# 2. Create a config file interactively
rustunnel setup
# → prompts for region and auth token, writes ~/.rustunnel/config.yml

# 3. Expose a local web server running on port 3000
rustunnel http 3000

# 4. Expose a raw TCP service (e.g. SSH on port 22)
rustunnel tcp 22
```

--------------------------------

### Rustunnel Setup Wizard Configuration Example

Source: https://rustunnel.com/docs/quickstart

Example interaction with the Rustunnel setup wizard, showing region selection and auth token input.

```text
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>

Created: /Users/you/.rustunnel/config.yml
```

--------------------------------

### Example Rustunnel Setup Session (Self-Hosted)

Source: https://rustunnel.com/docs/guides/client-guide

Illustrates an interactive session for 'rustunnel setup' when configuring a self-hosted Rustunnel server.

```bash
rustunnel setup — create ~/.rustunnel/config.yml

Region [auto / eu / us / ap / self-hosted] (default: auto): self-hosted

Tunnel server address: tunnel.internal.corp:4040

Auth token (leave blank to skip): my-token

Created: /Users/alice/.rustunnel/config.yml
Run `rustunnel start` to connect using this config.

```

--------------------------------

### Example Rustunnel Setup Session (Auto Region)

Source: https://rustunnel.com/docs/guides/client-guide

Demonstrates an interactive session for 'rustunnel setup' where the nearest region is automatically detected and selected.

```bash
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_abc123xyz

Created: /Users/alice/.rustunnel/config.yml
Run `rustunnel start` to connect using this config.

```

--------------------------------

### Install Dependencies with APT

Source: https://rustunnel.com/docs/guides/docker-deployment

Installs necessary packages including git, curl, Certbot with Cloudflare DNS plugin, Docker, and Docker Compose plugin. Enables and starts the Docker service.

```bash
apt update && apt install -y \
  git curl \
  certbot python3-certbot-dns-cloudflare \
  docker.io docker-compose-plugin

# Enable Docker to start on boot
systemctl enable --now docker

```

--------------------------------

### Install and Enable Rustunnel Systemd Service

Source: https://rustunnel.com/docs/guides/self-hosting

Install the rustunnel systemd service file, reload the systemd daemon, and then enable and start the service. Verify its status and monitor logs.

```bash
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
```

--------------------------------

### Start Rustunnel Client A

Source: https://rustunnel.com/docs/reference/load-balancing

Start the Rustunnel client using the configuration file, connecting to backend A.

```bash
./target/release/rustunnel start --config /tmp/lb-test.yml

```

--------------------------------

### Run Rustunnel Setup Wizard

Source: https://rustunnel.com/docs/quickstart

Initiates the Rustunnel setup wizard to configure the client with region and authentication token, creating ~/.rustunnel/config.yml.

```bash
rustunnel setup
```

--------------------------------

### Start Backend Server A

Source: https://rustunnel.com/docs/reference/load-balancing

Start a simple HTTP server on port 3000 to act as backend A.

```bash
python3 -m http.server 3000

```

--------------------------------

### Install rustunnel Server Binary

Source: https://rustunnel.com/docs/guides/self-hosting

Installs the rustunnel server binary to /usr/local/bin. Optionally installs the client binary as well.

```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

```

--------------------------------

### Start Rustunnel with Default Config

Source: https://rustunnel.com/docs/guides/client-guide

Starts the Rustunnel client using the default configuration file. The `start` command automatically attempts to reconnect.

```bash
rustunnel start
```

--------------------------------

### Start Backend A and Client A

Source: https://rustunnel.com/docs/guides/client-guide

Starts a local HTTP server on port 3000 and then launches the Rustunnel client using the load balancing test configuration.

```bash
# Terminal 1 — backend A
python3 -m http.server 3000

# Terminal 2 — client A
./target/release/rustunnel start --config /tmp/lb-test.yml

```

--------------------------------

### Start Rustunnel Client

Source: https://rustunnel.com/docs/guides/client-guide

Starts the Rustunnel client using either the default configuration file or a specified custom configuration file. The `start` command automatically attempts to reconnect and requires at least one tunnel to be defined.

```APIDOC
## Start Rustunnel Client

### Description
Starts the Rustunnel client. It can use a default configuration file or a custom one specified via the `--config` flag. The client automatically attempts to reconnect and requires at least one tunnel to be defined in the configuration.

### Usage
```bash
rustunnel start
rustunnel start --config /path/to/your/config.yml
```

### Options
* `--config <path>`: Specifies the path to a custom configuration file.
```

--------------------------------

### Start Local Mintlify Development Server

Source: https://rustunnel.com/docs/development

Navigate to your docs directory and run 'mint dev' to start a local preview. The preview will be available at http://localhost:3000.

```bash
mint dev

```

--------------------------------

### Install Dependencies with Apt

Source: https://rustunnel.com/docs/guides/self-hosting

Installs necessary packages for building and running rustunnel, including build tools and Certbot for Let's Encrypt.

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

```

--------------------------------

### Start Backend Server B

Source: https://rustunnel.com/docs/reference/load-balancing

Start a second simple HTTP server on port 3001 to act as backend B.

```bash
python3 -m http.server 3001

```

--------------------------------

### Install Mintlify CLI

Source: https://rustunnel.com/docs/development

Install the Mintlify CLI globally using npm. Ensure Node.js version 19 or higher is installed.

```bash
npm i -g mint

```

--------------------------------

### Install Rust Toolchain

Source: https://rustunnel.com/docs/guides/self-hosting

Installs the Rust toolchain using rustup. This should be run as a non-root user.

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

```

--------------------------------

### Install PostgreSQL

Source: https://rustunnel.com/docs/guides/self-hosting

Installs PostgreSQL and enables its systemd service. This is required for rustunnel's database backend.

```bash
apt install -y postgresql postgresql-contrib

# Start and enable the service
systemctl enable --now postgresql

```

--------------------------------

### Example: Create API Token

Source: https://rustunnel.com/docs/guides/client-guide

Provides a concrete example of creating an API token with a specified name, server address, and admin token. The generated token should be kept secure as it's only shown once.

```bash
rustunnel token create \
  --name "production-server" \
  --server tunnel.example.com:4040 \
  --admin-token admin_secret_here

```

--------------------------------

### Get Connection Info Response Example

Source: https://rustunnel.com/docs/guides/mcp-server

This is an example of the JSON response structure for `get_connection_info`. It provides the CLI command string needed to establish a tunnel when the MCP server cannot launch subprocesses.

```json
{
  "cli_command":  "rustunnel http 3000 --server eu.edge.rustunnel.com:4040 --token abc123",
  "server":       "eu.edge.rustunnel.com:4040",
  "install_url":  "https://github.com/joaoh82/rustunnel/releases/latest"
}

```

--------------------------------

### Rustunnel Configuration File Example

Source: https://rustunnel.com/docs/guides/client-guide

A comprehensive example of the `~/.rustunnel/config.yml` file, demonstrating settings for server address, authentication token, TLS verification, region preference, and named tunnel definitions.

```yaml
# Tunnel server address (required — choose a region)
server: eu.edge.rustunnel.com:4040

# Authentication token (required)
auth_token: rt_live_abc123...

# Skip TLS certificate verification — local dev ONLY, never use in production
insecure: false

# Region preference: auto (probe & pick nearest), or eu / us / ap.
# Omit for self-hosted / single-server setups.
region: auto

# Named tunnel definitions used by `rustunnel start`
tunnels:
  web:
    proto: http
    local_port: 3000
    local_host: localhost       # optional, defaults to localhost
    subdomain: myapp            # optional, requests a specific subdomain

  api:
    proto: http
    local_port: 8080
    subdomain: myapi

  database:
    proto: tcp
    local_port: 5432
```

--------------------------------

### Generated Rustunnel Configuration (Self-Hosted)

Source: https://rustunnel.com/docs/guides/client-guide

Example of a generated configuration file after running 'rustunnel setup' for a self-hosted server.

```yaml
# rustunnel configuration
# Documentation: https://github.com/joaoh82/rustunnel

server: tunnel.internal.corp:4040
auth_token: my-token
# region: not applicable (self-hosted)

# tunnels:
#   ...


```

--------------------------------

### Generated Rustunnel Configuration (Managed)

Source: https://rustunnel.com/docs/guides/client-guide

Example of a generated configuration file after running 'rustunnel setup' for a managed server.

```yaml
# rustunnel configuration
# Documentation: https://github.com/joaoh82/rustunnel

server: eu.edge.rustunnel.com:4040
auth_token: rt_live_abc123xyz
region: auto

# tunnels:
#   web:
#     proto: http
#     local_port: 3000
#   api:
#     proto: http
#     local_port: 8080
#     subdomain: myapi
#   database:
#     proto: tcp
#     local_port: 5432


```

--------------------------------

### Install Rustunnel Client from Source

Source: https://rustunnel.com/docs/guides/client-guide

Install the rustunnel client by cloning the repository, building from source, and placing the executable in your system's PATH. Requires Rust 1.75 or later.

```bash
git clone https://github.com/joaoh82/rustunnel
cd rustunnel
cargo build --release -p rustunnel-client
sudo install -Dm755 target/release/rustunnel /usr/local/bin/rustunnel
```

```bash
make deploy-client
```

--------------------------------

### Start Rustunnel with Custom Config

Source: https://rustunnel.com/docs/guides/client-guide

Starts the Rustunnel client using a specified custom configuration file. Ensure the configuration file defines at least one tunnel.

```bash
rustunnel start --config /etc/rustunnel/production.yml
```

--------------------------------

### Configure Multiple Tunnels

Source: https://rustunnel.com/docs/guides/client-guide

Use a configuration file with `rustunnel start` to define multiple tunnels over a single control connection. This example configures HTTP tunnels for frontend and backend services, and a TCP tunnel for metrics.

```yaml
server: tunnel.example.com:9000
auth_token: rt_live_abc123

tunnels:
  frontend:
    proto: http
    local_port: 3000
    subdomain: app
  backend:
    proto: http
    local_port: 8080
    subdomain: api
  metrics:
    proto: tcp
    local_port: 9090
```

```bash
rustunnel start
```

--------------------------------

### Verify Rustunnel Installation

Source: https://rustunnel.com/docs/quickstart

Checks if the Rustunnel client has been installed correctly by displaying its version.

```bash
rustunnel --version
```

--------------------------------

### Install rustunnel Plugin

Source: https://rustunnel.com/docs/guides/claude-plugin

Use this command to install the rustunnel plugin directly from the plugin marketplace within Claude Code.

```bash
/plugin install rustunnel

```

--------------------------------

### Install Rustunnel CLI (Homebrew)

Source: https://rustunnel.com/docs/quickstart

Installs the Rustunnel CLI client and MCP server using Homebrew on macOS and Linux. No Rust toolchain is required.

```bash
brew tap joaoh82/rustunnel
brew install rustunnel
```

--------------------------------

### Start Multiple Tunnels from Config

Source: https://rustunnel.com/docs/guides/client-guide

Use 'rustunnel start' to launch all tunnels defined in a configuration file. The default config path is '~/.rustunnel/config.yml', but can be overridden with '--config'.

```bash
rustunnel start [--config <path>]

```

--------------------------------

### Deploy rustunnel using Makefile

Source: https://rustunnel.com/docs/guides/self-hosting

A shortcut to build, install, and set up the systemd service for rustunnel using the provided Makefile.

```bash
sudo make deploy

```

--------------------------------

### Start Rustunnel Server with Docker Compose

Source: https://rustunnel.com/docs/guides/docker-deployment

Starts the Rustunnel server in detached mode using Docker Compose, applying the configurations defined in `deploy/docker-compose.yml`.

```bash
docker compose -f deploy/docker-compose.yml up -d

```

--------------------------------

### Run Rustunnel Server Locally

Source: https://rustunnel.com/docs/contribute

Start the Rustunnel server using the checked-in local configuration file. Ensure the self-signed certificate is generated beforehand.

```bash
cargo run -p rustunnel-server -- --config deploy/local/server.toml
```

--------------------------------

### Install rustunnel CLI

Source: https://rustunnel.com/docs/guides/claude-plugin

Install the rustunnel CLI using Homebrew on macOS/Linux, or download from GitHub releases. This CLI is required as the MCP server spawns it as a subprocess.

```bash
# Homebrew (macOS/Linux)
brew tap joaoh82/rustunnel
brew install rustunnel

# Or download from GitHub releases
# https://github.com/joaoh82/rustunnel/releases/latest

```

--------------------------------

### Start the rustunnel server in local development mode

Source: https://rustunnel.com/docs/guides/docker-deployment

Start the rustunnel server using Docker Compose with the local development configuration. Use the '-d' flag to detach the process and run it in the background.

```bash
docker compose -f deploy/docker-compose.local.yml up

```

```bash
docker compose -f deploy/docker-compose.local.yml up -d

```

--------------------------------

### Build Rustunnel from Source

Source: https://rustunnel.com/docs/quickstart

Builds the Rustunnel client from source, requiring Rust 1.76 or later. Installs the binary to /usr/local/bin.

```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
```

--------------------------------

### Start Backend B and Client B

Source: https://rustunnel.com/docs/guides/client-guide

Starts a second local HTTP server on port 3001 and launches another Rustunnel client. This client uses a configuration identical to Client A, except for the `local_port`.

```bash
# Terminal 3 — backend B
python3 -m http.server 3001

# Terminal 4 — client B
./target/release/rustunnel start --config /tmp/lb-test-b.yml

```

--------------------------------

### Start Local PostgreSQL Container for Tests

Source: https://rustunnel.com/docs/contribute

Use 'make db-start' to launch a PostgreSQL container for running integration tests. This container persists across reboots.

```bash
# Start the local PostgreSQL container (persists across reboots)
make db-start
```

--------------------------------

### Connect a Rustunnel Client

Source: https://rustunnel.com/docs/guides/self-hosting

Example command to connect a Rustunnel client to the server, forwarding a local port and specifying the server address and authentication token.

```bash
rustunnel http 3000 \
  --server edge.rustunnel.com:4040 \
  --token YOUR_ADMIN_TOKEN
```

--------------------------------

### Manual Plugin Installation

Source: https://rustunnel.com/docs/guides/claude-plugin

Clone the rustunnel repository and point Claude Code to the plugin directory for manual installation. Add the plugin path to your Claude Code settings for permanent loading.

```bash
git clone https://github.com/joaoh82/rustunnel.git
claude --plugin-dir rustunnel/plugins/claude-code/

```

```bash
claude plugin install --path rustunnel/plugins/claude-code/

```

--------------------------------

### Start Rustunnel Client B

Source: https://rustunnel.com/docs/reference/load-balancing

Start a second Rustunnel client, either by modifying the existing config or using a new one, ensuring it shares the same `group` and `group_key` but uses a different `local_port` (e.g., 3001).

```bash
echo "Modify /tmp/lb-test.yml to use local_port: 3001 and run a second `rustunnel start` command, or create a new config file with the same group/group_key and local_port: 3001."

```

--------------------------------

### Start Server with Monitoring Stack

Source: https://rustunnel.com/docs/guides/docker-deployment

Launches the Rustunnel server along with Prometheus and Grafana for monitoring. Access Grafana at http://<host>:3000 and Prometheus at http://<host>:9090.

```bash
docker compose -f deploy/docker-compose.yml --profile monitoring up -d
```

--------------------------------

### Install Git Hooks

Source: https://rustunnel.com/docs/contribute

Run this command once after cloning to activate the pre-push quality gate. This ensures code formatting and linting checks are performed before each push.

```bash
make install-hooks
```

--------------------------------

### rustunnel Server Configuration

Source: https://rustunnel.com/docs/guides/self-hosting

Example configuration file for the rustunnel server, specifying domain, ports, TLS settings, authentication, and database connection.

```toml
# /etc/rustunnel/server.toml

[server]
# Primary domain — must match your wildcard DNS record.
domain       = "edge.rustunnel.com"

# Ports for incoming tunnel traffic.
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 (e.g. http://localhost:3000 for local dev).
dashboard_origin = "http://localhost:3000"

# ── TLS ─────────────────────────────────────────────────────────────────────
[tls]
# Paths written by Certbot (see step 7).
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.
# When using Certbot (recommended), leave this false.
acme_enabled = false

# ── Auth ─────────────────────────────────────────────────────────────────────
[auth]
# Strong random secret — used as the admin token and for client auth.
# Generate with: openssl rand -hex 32
admin_token  = "your-admin-token-here"
require_auth = true

# ── Database ─────────────────────────────────────────────────────────────────
[database]
# PostgreSQL connection URL — the database and user must exist before starting
# the server (see step 5 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.

```

--------------------------------

### Rustunnel Debug Logging Examples

Source: https://rustunnel.com/docs/guides/client-guide

These examples demonstrate how to set the `RUST_LOG` environment variable to control logging levels for Rustunnel and other crates. Log output is directed to stderr.

```bash
# Enable debug logging for all crates
RUST_LOG=debug rustunnel http 3000

```

```bash
# Enable debug only for rustunnel internals
RUST_LOG=rustunnel=debug rustunnel http 3000

```

```bash
# Quiet mode (errors only)
RUST_LOG=error rustunnel http 3000

```

--------------------------------

### Start Server with Monitoring and Set Grafana Password

Source: https://rustunnel.com/docs/guides/docker-deployment

Starts the Rustunnel server, Prometheus, and Grafana after setting a random, secure password for the Grafana admin user. Ensure the GRAFANA_PASSWORD environment variable is exported before running.

```bash
export GRAFANA_PASSWORD="$(openssl rand -hex 16)"
docker compose -f deploy/docker-compose.yml --profile monitoring up -d
```

--------------------------------

### Start a UDP Tunnel

Source: https://rustunnel.com/docs/reference/udp-tunnels

Use this command to start a UDP tunnel. Specify the local UDP port, the server address, and authentication details. The client will output the allocated public UDP endpoint upon success.

```bash
rustunnel udp 53 --server localhost:4040 --insecure --token dev-secret-change-me
```

--------------------------------

### Create Tunnel Request Example

Source: https://rustunnel.com/docs/guides/mcp-server

This is an example of the JSON response structure when creating a tunnel. The MCP server spawns `rustunnel` as a background subprocess and polls the API until the tunnel appears.

```json
{
  "public_url": "https://abc123.eu.edge.rustunnel.com",
  "tunnel_id":  "a1b2c3d4-...",
  "protocol":   "http"
}

```

--------------------------------

### Clone the rustunnel repository

Source: https://rustunnel.com/docs/guides/docker-deployment

Clone the repository to get the necessary files for deployment. Navigate into the cloned directory.

```bash
git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel

```

--------------------------------

### Create Token via CLI and REST API

Source: https://rustunnel.com/docs/guides/mcp-server

Examples of creating API tokens for self-hosted Rustunnel servers. The CLI command is straightforward, while the REST API requires authentication with an admin token and a JSON payload.

```bash
# CLI
rustunnel token create --name agent-session

```

```bash
# REST API
curl -X POST https://eu.edge.rustunnel.com:8443/api/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "agent-session"}'

```

--------------------------------

### Rustunnel Tunnel Open Confirmation

Source: https://rustunnel.com/docs/quickstart

Example output when a Rustunnel tunnel is successfully opened, showing the assigned public URL.

```text
  Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms
✓ tunnel open  https://abc123.eu.edge.rustunnel.com
```

--------------------------------

### Testing Load Balancing Locally

Source: https://rustunnel.com/docs/reference/load-balancing

A step-by-step guide to perform a local end-to-end smoke test for the load balancing feature.

```APIDOC
## Testing the feature locally

Quick end-to-end smoke test against a self-hosted edge with `[load_balancing] enabled = true`.
Spin up two clients with the same `(group, group_key)`, point them at separate local backends, and hammer the public URL — both backends should serve.

1. **Build the client from source**
   ```
   git clone https://github.com/joaoh82/rustunnel
   cd rustunnel
   cargo build --release -p rustunnel-client
   ```

2. **Drop a config that opts into a group**
   ```
   cat > /tmp/lb-test.yml <<'EOF'
   server: tunnel.example.com:4040
   auth_token: "your-token"

   tunnels:
     a:
       proto: http
       local_port: 3000
       subdomain: lbtest
       group: web
       group_key: shared-secret-for-lb-test
       health_check:
         type: tcp
   EOF
   ```

3. **Start backend A on :3000**
   ```
   python3 -m http.server 3000
   ```

4. **Start client A pointing at backend A**
   ```
   ./target/release/rustunnel start --config /tmp/lb-test.yml
   ```

5. **Start backend B on :3001**
   In a separate terminal:
   ```
   python3 -m http.server 3001
   ```

6. **Start client B with `local_port: 3001`**
   Either edit `/tmp/lb-test.yml` and run a second `rustunnel start`, or use a second config file with the same `group` / `group_key` and `local_port: 3001`.

7. **Hammer the public URL**
   ```
   for i in $(seq 1 50); do
     curl -fsS https://lbtest.tunnel.example.com/ -o /dev/null -w "%{{http_code}}\n"
   done
   ```
   Both backends should see roughly half of the requests in their access logs.

8. **Verify via the metrics endpoint**
   ```
   ssh root@tunnel.example.com 'curl -sf http://127.0.0.1:9090/metrics' \
     | grep '^rustunnel_group_'
   ```
   Expect output like:
   ```
   rustunnel_group_members{group="web",region="eu",healthy="true"} 2
   rustunnel_group_members{group="web",region="eu",healthy="false"} 0
   rustunnel_group_dispatches_total{group="web",region="eu"} 50
   rustunnel_group_health_failures_total{group="web",region="eu",kind="tcp"} 0
   ```

9. **Validate failover**
   Kill one of the local backends. The probe loop on that client marks it unhealthy after `max_failed * interval_secs` seconds; subsequent requests all land on the survivor. Restart the backend — the probe re-registers it as healthy and dispatch distributes again.
```

--------------------------------

### Start Monitoring Stack with Docker

Source: https://rustunnel.com/docs/guides/self-hosting

Run the full monitoring stack including Prometheus and Grafana using Docker. The default Grafana password is 'changeme'.

```bash
make docker-run-monitoring
# Grafana:    http://localhost:3000  (admin / changeme)
# Prometheus: http://localhost:9090

```

--------------------------------

### Configure rustunnel Plugin

Source: https://rustunnel.com/docs/guides/claude-plugin

Run this command to reconfigure the rustunnel plugin after initial installation, allowing you to change server address, API URL, and API token.

```bash
/plugin configure rustunnel

```

--------------------------------

### Configure wildcard DNS for *.localhost using dnsmasq on macOS

Source: https://rustunnel.com/docs/guides/docker-deployment

Set up dnsmasq to resolve all subdomains of '.localhost' to '127.0.0.1'. This allows accessing HTTP tunnel URLs like 'http://abc123.localhost:8080' directly in a browser. Ensure dnsmasq is installed and started.

```bash
brew install dnsmasq
echo "address=/.localhost/127.0.0.1" | sudo tee -a $(brew --prefix)/etc/dnsmasq.conf
sudo brew services start dnsmasq
sudo mkdir -p /etc/resolver
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/localhost

```

--------------------------------

### Create System User and Directories

Source: https://rustunnel.com/docs/guides/self-hosting

Sets up a dedicated system user and directories for rustunnel, ensuring proper ownership and permissions.

```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

```

--------------------------------

### Set Grafana Password and Start Monitoring

Source: https://rustunnel.com/docs/guides/self-hosting

Before starting the monitoring stack in production, set a strong password for Grafana by exporting the GRAFANA_PASSWORD environment variable.

```bash
export GRAFANA_PASSWORD=your-strong-password
make docker-run-monitoring
```

--------------------------------

### Rustunnel Reconnection Delay Examples

Source: https://rustunnel.com/docs/guides/client-guide

These examples demonstrate the exponential backoff schedule for automatic reconnections, including random jitter. The maximum delay is capped at 60 seconds.

```text
  Reconnecting in 2.3s (attempt 2)…
  Reconnecting in 5.1s (attempt 3)…

```

--------------------------------

### Build Rustunnel Client

Source: https://rustunnel.com/docs/reference/load-balancing

Clone the repository and build the Rustunnel client in release mode.

```bash
git clone https://github.com/joaoh82/rustunnel
cd rustunnel
cargo build --release -p rustunnel-client

```

--------------------------------

### Configure Rustunnel Server TOML

Source: https://rustunnel.com/docs/guides/docker-deployment

Sets the server domain, TLS certificate paths, and admin authentication token in the `deploy/server.toml` configuration file. `require_auth` should be set to `true` for production environments.

```toml
[server]
domain = "edge.rustunnel.com"   # ← your domain

[tls]
cert_path = "/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem"
key_path  = "/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem"

[auth]
admin_token  = "PASTE_YOUR_GENERATED_TOKEN_HERE"
require_auth = true

```

--------------------------------

### Rustunnel Tunnel Status Output

Source: https://rustunnel.com/docs/guides/client-guide

Example of the terminal output after a rustunnel connection is established, showing the public URL for the exposed service.

```text
╭────────────────────────────────────────────────────────────╮
│                         rustunnel                          │
├────────────────────────────────────────────────────────────┤
│  HTTP [myapp] → localhost:3000                             │
│   https://myapp.tunnel.example.com                        │
╰────────────────────────────────────────────────────────────╯

  ✓ Tunnels active. Press Ctrl-C to quit.
```

--------------------------------

### Create Cloudflare Credentials File

Source: https://rustunnel.com/docs/guides/docker-deployment

Creates a directory for Let's Encrypt credentials and a Cloudflare INI file to store the API token. Sets restrictive permissions on the credentials file.

```bash
mkdir -p /etc/letsencrypt
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

```

--------------------------------

### Build the Docker image for rustunnel-server

Source: https://rustunnel.com/docs/guides/docker-deployment

Build the Docker image using the provided Dockerfile. This command compiles the Rust server and bakes the dashboard UI into the binary. Subsequent builds are faster due to Docker layer caching.

```bash
make docker-build
# equivalent: docker build -f deploy/Dockerfile -t rustunnel-server:latest .

```

--------------------------------

### Rustunnel Startup Box Output

Source: https://rustunnel.com/docs/guides/client-guide

This is the typical startup box displayed once all tunnels are registered. It shows active HTTP and TCP tunnels with their local and public endpoints. Color coding is used for different elements.

```text
╭────────────────────────────────────────────────────────────╮
│                         rustunnel                          │
├────────────────────────────────────────────────────────────┤
│   HTTP [myapp] → localhost:3000                            │
│   https://myapp.tunnel.example.com                        │
│   TCP  [ssh]   → localhost:22                             │
│   tcp://tunnel.example.com:34521                          │
╰────────────────────────────────────────────────────────────╯

  ✓ Tunnels active. Press Ctrl-C to quit.

```

--------------------------------

### Update Rustunnel Server

Source: https://rustunnel.com/docs/guides/self-hosting

Command to pull the latest code, rebuild the release binary, install it, and restart the server. This is a convenient way to keep the server up-to-date.

```bash
cd ~/rustunnel && sudo make update-server
```

--------------------------------

### Create PostgreSQL Database and User

Source: https://rustunnel.com/docs/guides/self-hosting

Creates a dedicated PostgreSQL user and database for rustunnel, granting all necessary privileges.

```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

```

--------------------------------

### Build rustunnel Release Binaries

Source: https://rustunnel.com/docs/guides/self-hosting

Clones the rustunnel repository and builds the release binaries for the server and client.

```bash
git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel
cargo build --release -p rustunnel-server -p rustunnel-client

```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://rustunnel.com/docs/guides/mcp-server

Configure the MCP server for Claude Desktop by adding rustunnel-mcp details to the configuration file. Ensure you replace '<your-token>' with your actual rustunnel token.

```json
{
  "mcpServers": {
    "rustunnel": {
      "command": "rustunnel-mcp",
      "args": [
        "--server", "eu.edge.rustunnel.com:4040",
        "--api",    "https://eu.edge.rustunnel.com:8443"
      ],
      "env": {
        "RUSTUNNEL_TOKEN": "<your-token>"
      }
    }
  }
}

```

--------------------------------

### Disable Rustunnel Reconnection

Source: https://rustunnel.com/docs/guides/client-guide

Use the `--no-reconnect` flag for scripting or CI environments where automatic retries are not desired. The example shows chaining with `echo` to indicate tunnel exit.

```bash
rustunnel http 3000 --no-reconnect || echo "Tunnel exited"

```

--------------------------------

### Build rustunnel-mcp Release

Source: https://rustunnel.com/docs/guides/mcp-server

Build the rustunnel-mcp binary for release. This command produces the executable in the target/release directory.

```bash
make release-mcp
# Produces: target/release/rustunnel-mcp

# Install to PATH
sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp

```

--------------------------------

### Rustunnel Auto-select Region Output Example

Source: https://rustunnel.com/docs/guides/client-guide

This output shows the client probing regions and selecting the nearest one based on TCP connect time. Unreachable regions are penalized.

```text
  Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms

```

--------------------------------

### Expected Metrics Output

Source: https://rustunnel.com/docs/reference/load-balancing

Example output from the metrics endpoint, showing group members, dispatches, and health failures. This helps validate the load balancing and health check configurations.

```text
rustunnel_group_members{group="web",region="eu",healthy="true"} 2
ustunnel_group_members{group="web",region="eu",healthy="false"} 0
ustunnel_group_dispatches_total{group="web",region="eu"} 50
ustunnel_group_health_failures_total{group="web",region="eu",kind="tcp"} 0

```

--------------------------------

### Build Rustunnel Docker Image

Source: https://rustunnel.com/docs/guides/docker-deployment

Builds the Docker image for the Rustunnel server using the provided Dockerfile and tags it as `rustunnel-server:latest`.

```bash
docker build -f deploy/Dockerfile -t rustunnel-server:latest .

```

--------------------------------

### Run All Rustunnel Tests

Source: https://rustunnel.com/docs/contribute

Execute the full test suite, including unit and integration tests, for the entire workspace. Ensure the PostgreSQL container is running.

```bash
# Full suite: unit + integration
make test
```

--------------------------------

### Expose a local service via P2P tunnel

Source: https://rustunnel.com/docs/reference/p2p-tunnels

Use this command to expose a local service to a P2P tunnel. Replace `27015` with your service's port, `my-game` with your desired tunnel name, and `shared-secret-123` with a strong secret.

```bash
rustunnel p2p 27015 --name my-game --secret "shared-secret-123"
```

--------------------------------

### Configure UDP Tunnels in Config File

Source: https://rustunnel.com/docs/reference/udp-tunnels

Define UDP tunnels in the Rustunnel configuration file. Each tunnel can be named and configured with its protocol and local port. Use 'rustunnel start' to launch all configured tunnels.

```yaml
tunnels:
  gameserver:
    proto: udp
    local_port: 27015

  dns:
    proto: udp
    local_port: 53
```

--------------------------------

### Build rustunnel-mcp Without Dashboard

Source: https://rustunnel.com/docs/guides/mcp-server

Build the rustunnel-mcp binary without including the dashboard UI step. This is useful for a leaner build.

```bash
cargo build --release -p rustunnel-mcp

```

--------------------------------

### Allow UDP Port Range in Firewall

Source: https://rustunnel.com/docs/reference/udp-tunnels

If the public UDP port is unreachable, ensure your host firewall is open for the configured UDP port range. This example shows how to allow ports 20100 through 20199.

```bash
ufw allow 20100:20199/udp
```

--------------------------------

### Run Mintlify on a Custom Port

Source: https://rustunnel.com/docs/development

Use the '--port' flag with 'mint dev' to specify a custom port for the local preview. If the specified port is in use, Mintlify will automatically select the next available port.

```bash
mint dev --port 3333

```

```text
Port 3000 is already in use. Trying 3001 instead.

```

--------------------------------

### Generate Self-Signed Certificate for Local Development

Source: https://rustunnel.com/docs/contribute

Create a self-signed certificate and private key in '/tmp/rustunnel-dev' for local TLS testing. This is required for running the server locally with HTTPS.

```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"
```

--------------------------------

### Clone the Rustunnel Repository

Source: https://rustunnel.com/docs/contribute

Fork the repository on GitHub and clone your fork locally. Navigate into the cloned directory to begin development.

```bash
git clone https://github.com/<your-username>/rustunnel.git
cd rustunnel
```

--------------------------------

### Build Docker Image

Source: https://rustunnel.com/docs/guides/docker-deployment

Builds the Docker image for the Rustunnel server. This command is typically used as part of the update process.

```bash
docker build -f deploy/Dockerfile -t rustunnel-server:latest .
```
Tokens:
Raw