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

How to contribute to rustunnel — an open-source, self-hosted tunnel server written in Rust.

Contributions are welcome! rustunnel is open-source under the [AGPLv3 license](https://github.com/joaoh82/rustunnel/blob/main/LICENSE). Whether it's a bug fix, a new feature, or improved documentation, we appreciate your help.

## Before you start

For larger changes or new features, **open an issue first** to discuss the approach. This avoids duplicate effort and ensures the change is aligned with the project direction.

For small fixes (typos, docs, minor bugs) you can go straight to a pull request.

***

## Getting started

<Steps>
  <Step title="Fork and clone">
    Fork the repository on GitHub, then clone your fork:

    ```bash theme={null}
    git clone https://github.com/<your-username>/rustunnel.git
    cd rustunnel
    ```
  </Step>

  <Step title="Install dependencies">
    You need:

    | Tool           | Version | Notes                                      |
    | -------------- | ------- | ------------------------------------------ |
    | Rust toolchain | 1.76+   | Install via [rustup](https://rustup.rs)    |
    | `pkg-config`   | any     | Required by `reqwest` (TLS)                |
    | `libssl-dev`   | any     | On Debian/Ubuntu: `apt install libssl-dev` |
    | Node.js + npm  | 18+     | Only needed to rebuild the dashboard UI    |
    | Docker         | any     | Required to run the test database          |
  </Step>

  <Step title="Install git hooks">
    Run this once after cloning to activate the pre-push quality gate:

    ```bash theme={null}
    make install-hooks
    ```

    Every `git push` will automatically run `cargo fmt` checks and `cargo clippy` before the push is allowed.
  </Step>

  <Step title="Create a feature branch">
    Branch off `main` with a descriptive name:

    ```bash theme={null}
    git checkout -b fix/heartbeat-timeout
    # or
    git checkout -b feat/tcp-region-selection
    ```
  </Step>
</Steps>

***

## Local development

### Build

```bash theme={null}
# Debug build (fast compile)
cargo build --workspace

# Or via Make
make build
```

### Run the server locally

Generate a self-signed certificate for local testing:

```bash theme={null}
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"
```

Start the server with the checked-in local config:

```bash theme={null}
cargo run -p rustunnel-server -- --config deploy/local/server.toml
```

### Run the client locally

With the server running, expose a local service:

```bash theme={null}
# 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
```

<Note>`--insecure` skips TLS verification — required when using the self-signed cert. Never use it against a production server.</Note>

***

## Running 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 theme={null}
# Start the local PostgreSQL container (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

# Run a single test
TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test \
  cargo test <test_name> -p <crate_name>

# Stop PostgreSQL when done
make db-stop
```

***

## Code quality

Before opening a PR, make sure these pass:

```bash theme={null}
# Format check
cargo fmt --all -- --check

# Lint (zero warnings policy)
cargo clippy --workspace --all-targets -- -D warnings

# Both at once
make check
```

CI runs the same checks on every push and pull request.

***

## Opening a pull request

1. Push your branch to your fork and open a PR against `main`.
2. Write a clear description of **what changed and why**.
3. Make sure CI is green — format, Clippy, and all tests.
4. A maintainer will review and merge.

### PR guidelines

* **Keep PRs focused** — one logical change per PR. Avoid bundling unrelated fixes.
* **Add or update tests** for any new behaviour. The integration test suite in `tests/integration/` is the right place for end-to-end scenarios.
* **Follow existing code style** — `cargo fmt` is enforced by CI.
* **Update documentation** if you change user-facing behaviour (flags, config keys, API endpoints).

***

## Project structure

| Path                         | Purpose                                                    |
| ---------------------------- | ---------------------------------------------------------- |
| `crates/rustunnel-protocol/` | Shared `ControlFrame` types and serialization              |
| `crates/rustunnel-server/`   | Server: control plane, HTTP/TCP edges, dashboard, TLS      |
| `crates/rustunnel-client/`   | CLI client with auto-reconnect and local port forwarding   |
| `crates/rustunnel-mcp/`      | MCP server for AI agent integration                        |
| `dashboard-ui/`              | Next.js dashboard frontend                                 |
| `deploy/`                    | Dockerfiles, compose files, systemd unit, config templates |
| `tests/integration/`         | End-to-end tests (real server + real PostgreSQL)           |
| `docs/`                      | Public documentation source                                |

***

## Useful make targets

| Target               | Description                                |
| -------------------- | ------------------------------------------ |
| `make build`         | Debug build of all workspace crates        |
| `make release`       | Optimized release build                    |
| `make check`         | `cargo fmt` check + `cargo clippy`         |
| `make test`          | Full test suite (requires `make db-start`) |
| `make db-start`      | Start the local PostgreSQL container       |
| `make db-stop`       | Stop the local PostgreSQL container        |
| `make install-hooks` | Install the pre-push git hook              |
| `make docker-build`  | Build the server Docker image              |

***

## License

By contributing you agree that your work will be licensed under the [GNU AGPLv3 License](https://github.com/joaoh82/rustunnel/blob/main/LICENSE).

***

## Contact

**João Henrique Machado Silva**

* GitHub: [@joaoh82](https://github.com/joaoh82)
* Issues & feature requests: [GitHub Issues](https://github.com/joaoh82/rustunnel/issues)

***

## Related pages

<CardGroup>
  <Card title="Architecture" icon="book-open" href="/docs/guides/architecture">
    Understand the control protocol, yamux data plane, and crate structure before diving into the code.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Install the client and open your first tunnel in three steps.
  </Card>

  <Card title="Client guide" icon="terminal" href="/docs/guides/client-guide">
    Every command, flag, and config option for the rustunnel CLI client.
  </Card>

  <Card title="Self-hosting" icon="server" href="/docs/guides/self-hosting">
    Run your own rustunnel server on a VPS with systemd and Let's Encrypt.
  </Card>
</CardGroup>


# Using rustunnel from an AI agent or LLM harness
Source: https://rustunnel.com/docs/guides/agent-integration

Copy-paste MCP config for Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Cline, and any custom MCP client — plus a one-command installer and a programmatic JSON-RPC example. Let your agent create, list, and close tunnels in plain language.

rustunnel ships an **MCP server** (`rustunnel-mcp`) that exposes tunnel management as tools any [Model Context Protocol](https://modelcontextprotocol.io) client can call. Once it's wired into your harness, you can just say:

> "Create an HTTP tunnel to my service on port 3000."
> "Expose port 5432 over TCP so I can reach my database."
> "Spin up a load-balanced pool across ports 3000 and 3001 with a health check."

This guide is the one-stop reference for adding rustunnel to **Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Cline, or any custom MCP agent**. For the deeper server and tool reference, see the [MCP server guide](/docs/guides/mcp-server).

***

## 1. Prerequisites

You need two binaries on your `PATH`:

* `rustunnel` — the client (the MCP server spawns it to open tunnels)
* `rustunnel-mcp` — the MCP server itself

```bash theme={null}
# Homebrew (macOS / Linux)
brew tap joaoh82/rustunnel && brew install rustunnel

# Or build from source
git clone https://github.com/joaoh82/rustunnel.git && cd rustunnel
make release          # builds rustunnel, rustunnel-server, rustunnel-mcp
sudo install -m755 target/release/rustunnel     /usr/local/bin/rustunnel
sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp
```

## 2. Get an API token (one-time)

<Info>
  This is the **one required user step**. Everything else is config you can copy-paste.
</Info>

rustunnel requires an API token. **You only need to do this once.**

* **Hosted (rustunnel.com):** sign up free at [rustunnel.com](https://rustunnel.com), then go to **Dashboard → API Keys** and create a key. No waiting list.
* **Self-hosted:** run `rustunnel token create --name agent --server <host>:4040 --admin_token <admin>`, or create one from your dashboard.

Set it as `RUSTUNNEL_TOKEN` in the MCP config below. When that variable is set, the agent never has to pass the token on individual calls.

## 3. The two server settings

| Setting                      | Hosted example                       | Self-hosted example               | Local dev               |
| ---------------------------- | ------------------------------------ | --------------------------------- | ----------------------- |
| `--server` (control plane)   | `eu.edge.rustunnel.com:4040`         | `tunnel.example.com:4040`         | `localhost:4040`        |
| `--api` (dashboard REST API) | `https://eu.edge.rustunnel.com:8443` | `https://tunnel.example.com:8443` | `http://localhost:4041` |

Add `--insecure` only for local dev with self-signed certs.

***

## 4. Quick install (any harness)

The [installer](https://github.com/joaoh82/rustunnel/blob/main/integrations/install.sh) prompts for your token and writes the right config for the harness you pick:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/joaoh82/rustunnel/main/integrations/install.sh | bash
# or, from a clone:
./integrations/install.sh
```

It supports `claude-code`, `claude-desktop`, `codex`, `cursor`, `windsurf`, `cline`, and `generic` (prints a snippet). Run `./integrations/install.sh --help` for non-interactive flags.

***

## 5. Per-harness configuration

Ready-to-edit templates live in the [`integrations/`](https://github.com/joaoh82/rustunnel/tree/main/integrations) folder. In every template, replace the placeholder token with your own, and swap the `--server` / `--api` values if you self-host.

### Claude Code

**Plugin (recommended — zero config):**

```text theme={null}
/plugin install rustunnel
/plugin configure rustunnel     # prompts for server, API URL, token
```

See the [Claude Code plugin guide](/docs/guides/claude-plugin).

**Manual `.mcp.json`** in your project root — see the [template](https://github.com/joaoh82/rustunnel/blob/main/integrations/claude-code/.mcp.json):

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

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Use the same `mcpServers` shape as above — [template](https://github.com/joaoh82/rustunnel/blob/main/integrations/claude-desktop/config.json).

### Codex (OpenAI)

Codex reads MCP servers from `~/.codex/config.toml` — [template](https://github.com/joaoh82/rustunnel/blob/main/integrations/codex/config.toml):

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

Codex also reads an `AGENTS.md` at the repo root for guidance.

### Cursor

Project: `.cursor/mcp.json`. Global: `~/.cursor/mcp.json`. Same `mcpServers` shape — [template](https://github.com/joaoh82/rustunnel/blob/main/integrations/cursor/mcp.json).

### Windsurf

`~/.codeium/windsurf/mcp_config.json`. Same shape — [template](https://github.com/joaoh82/rustunnel/blob/main/integrations/windsurf/mcp_config.json).

### Cline (VS Code)

`cline_mcp_settings.json` (via the Cline MCP settings UI). Same shape — [template](https://github.com/joaoh82/rustunnel/blob/main/integrations/cline/cline_mcp_settings.json).

### Generic / custom agent

Any MCP client uses the same `command` + `args` + `env`. Use the [generic template](https://github.com/joaoh82/rustunnel/blob/main/integrations/generic/mcp.json).

For a programmatic agent, spawn `rustunnel-mcp` and speak newline-delimited JSON-RPC 2.0 over stdin/stdout:

```python theme={null}
import subprocess, json, os

proc = subprocess.Popen(
    ["rustunnel-mcp", "--server", "eu.edge.rustunnel.com:4040",
     "--api", "https://eu.edge.rustunnel.com:8443"],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE,
    env={**os.environ, "RUSTUNNEL_TOKEN": "<your-token>"},
)

def call(method, params=None, _id=[0]):
    _id[0] += 1
    msg = {"jsonrpc": "2.0", "id": _id[0], "method": method}
    if params: msg["params"] = params
    proc.stdin.write(json.dumps(msg).encode() + b"\n"); proc.stdin.flush()
    return json.loads(proc.stdout.readline())

call("initialize", {"protocolVersion": "2024-11-05"})
print(call("tools/call", {"name": "create_tunnel",
      "arguments": {"local_port": 3000, "protocol": "http"}}))
```

***

## 6. Available tools

<Note>
  Every authenticated tool accepts an optional `token` argument. Omit it when `RUSTUNNEL_TOKEN` is set in the MCP config.
</Note>

| Tool                  | Purpose                                                                        |
| --------------------- | ------------------------------------------------------------------------------ |
| `create_tunnel`       | Open a tunnel and get a public URL. HTTP/TCP/UDP, P2P, and load-balanced pools |
| `close_tunnel`        | Close a tunnel by ID                                                           |
| `list_tunnels`        | List active tunnels                                                            |
| `get_tunnel_history`  | Past tunnel activity (audit)                                                   |
| `list_regions`        | Available server regions (no auth)                                             |
| `get_connection_info` | CLI command / config for manual runs (cloud sandboxes)                         |

### `create_tunnel` arguments

| Argument              | When           | Description                                                                                     |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `local_port`          | always         | Local port the service listens on                                                               |
| `protocol`            | always         | `http`, `tcp`, `udp`, or `p2p`                                                                  |
| `token`               | optional       | Falls back to `RUSTUNNEL_TOKEN`                                                                 |
| `subdomain`           | http           | Custom subdomain                                                                                |
| `region`              | optional       | `eu` / `us` / `ap`; omit to auto-select                                                         |
| `local_host`          | optional       | Forward to another host (default `localhost`)                                                   |
| `secret`              | p2p            | Shared secret (publisher and subscriber match)                                                  |
| `peer_name`           | p2p publish    | Publish under this name                                                                         |
| `peer_target`         | p2p connect    | Connect to this published name                                                                  |
| `group` + `group_key` | load balancing | Join a pool (http/tcp); members share the key                                                   |
| `health_check`        | optional       | `{ type: tcp\|http, path, interval_secs, timeout_secs, max_failed, expect_2xx, alert_webhook }` |

See the [MCP server guide](/docs/guides/mcp-server) for the full tool reference, [load balancing](/docs/reference/load-balancing) for pools and health checks, and [P2P tunnels](/docs/reference/p2p-tunnels) for peer-to-peer details.

***

## 7. Security notes

* Tokens travel to the server over HTTPS. Use `--insecure` only in local dev.
* The `RUSTUNNEL_TOKEN` env var keeps the token out of tool-call payloads and chat history — prefer it over passing `token` inline.
* Child `rustunnel` processes spawned by `create_tunnel` are killed when the MCP server exits; temp config files for load-balanced tunnels are cleaned up too.
* Protect any config file you save: `chmod 600 ~/.rustunnel/config.yml`.

***

## Related pages

<CardGroup>
  <Card title="MCP server" icon="server" href="/docs/guides/mcp-server">
    Full reference for rustunnel-mcp: every tool, parameter, and response shape.
  </Card>

  <Card title="Claude Code plugin" icon="plug" href="/docs/guides/claude-plugin">
    Skip the manual config — install the plugin with one command in Claude Code.
  </Card>

  <Card title="Load balancing" icon="route" href="/docs/reference/load-balancing">
    How load-balanced pools and health checks work for tunnels your agent creates.
  </Card>

  <Card title="P2P tunnels" icon="network" href="/docs/reference/p2p-tunnels">
    Direct peer-to-peer tunnels with shared secrets and named peers.
  </Card>

  <Card title="AI tools hub" icon="bot" href="https://rustunnel.com/ai-tools">
    Per-harness setup pages — Claude Code, Cursor, Windsurf, generic MCP — with agent-ready prompts.
  </Card>

  <Card title="Agent manual" icon="file-lines" href="https://rustunnel.com/agents.md">
    Copy-paste recipes and an FAQ for AI agents, served as plain markdown.
  </Card>
</CardGroup>


# rustunnel Architecture — control plane, data plane, and yamux multiplexing
Source: https://rustunnel.com/docs/guides/architecture

Internal architecture of rustunnel: control protocol (JSON over WebSocket), data plane (yamux multiplexed binary), concurrency model (Tokio), and the crate structure of the open-source tunnel server.

## Overview

rustunnel is a **self-hosted reverse tunnel** built in Rust: it lets a client behind NAT or a firewall expose local TCP services to the internet via a central server that has a public IP address.

It is architecturally similar to ngrok or Cloudflare Tunnel — see the [ngrok-vs-rustunnel breakdown](https://rustunnel.com/blog/ngrok-alternative) for a feature-level comparison — but designed to be simple, auditable, and [self-hosted on any VPS](/docs/guides/self-hosting).

Key design choices:

* **WebSocket transport** — works through any HTTP proxy or firewall that allows HTTPS.
* **yamux multiplexing** — a single data WebSocket carries streams for all proxied connections simultaneously.
* **Two-connection model** — control plane (JSON frames) and data plane (binary yamux frames) are separated.
* **Tokio async runtime** — all I/O is non-blocking; each session runs in a handful of lightweight tasks.
* **TLS everywhere** — all external connections are encrypted via rustls (ACME or static PEM).

***

## High-Level Topology

```text theme={null}
                         INTERNET
                            │
              ┌─────────────▼──────────────┐
              │        rustunnel-server      │
              │                              │
              │  ┌──────────┐  ┌──────────┐ │
 Browser  ───►│  │HTTP Edge │  │TCP Edge  │ │
 / Client     │  │:80/:443  │  │:xxxxx    │ │
              │  └────┬─────┘  └────┬─────┘ │
              │       │             │       │
              │  ┌────▼─────────────▼─────┐ │
              │  │      TunnelCore         │ │
              │  │  (routing table +       │ │
              │  │   pending conn map)     │ │
              │  └────────────┬───────────┘ │
              │               │             │
              │  ┌────────────▼───────────┐ │
              │  │  Control-Plane WS      │ │
              │  │  :4040  /_control      │ │
              │  │  :4040  /_data/<id>    │ │
              │  └────────────────────────┘ │
              └──────────────┬──────────────┘
                             │  WebSocket (TLS)
                    ┌────────▼──────────┐
                    │  rustunnel client  │
                    │                    │
                    │  ┌──────────────┐ │
                    │  │ Control loop  │ │
                    │  └──────────────┘ │
                    │  ┌──────────────┐ │
                    │  │ yamux driver  │ │
                    │  └──────────────┘ │
                    │  ┌──────────────┐ │
                    │  │ Proxy tasks   │ │
                    │  └──────────────┘ │
                    └────────┬──────────┘
                             │  TCP
              ┌──────────────▼───────────────┐
              │         Local Service          │
              │  (web server, SSH, DB, etc.)   │
              └───────────────────────────────┘
```

***

## Server Subsystems

The server is a single binary (`rustunnel-server`) composed of six concurrently running subsystems:

```text theme={null}
rustunnel-server
├── a) Control-plane WebSocket server  (:4040)
│      /_control  — JSON control frames
│      /_data/<session_id>  — binary yamux frames
├── b) HTTP + HTTPS edge proxy  (:80, :443)
├── c) TCP edge proxy  (dynamic ports)
├── d) Dashboard REST API + SPA  (:4041)
├── e) Prometheus metrics endpoint  (:9090)
└── f) ACME certificate renewal task (background)
```

All subsystems share a single `Arc<TunnelCore>` routing table.

### a) Control-Plane WebSocket Server

Handles two routes:

* **`/_control`** — One persistent WebSocket per client. Manages authentication, tunnel registration, and heartbeats.
* **`/_data/<session_id>`** — One persistent WebSocket per client session. Carries raw yamux frames for all proxied connections belonging to that session.

Each `/_control` connection spawns a **session task** that runs the control loop for that client.

### b) HTTP / HTTPS Edge Proxy

Listens on ports 80 and 443. For each incoming HTTP request:

1. Extracts the `Host` header subdomain (e.g. `myapp` from `myapp.tunnel.example.com`).
2. Looks up the subdomain in `TunnelCore.http_routes`.
3. If found, allocates a `conn_id`, stores a oneshot sender in `TunnelCore.pending_conns`, and sends a `NewConnection` frame to the owning session.
4. Waits for the yamux stream to arrive (delivered by the session's yamux driver).
5. Copies bytes bidirectionally between the incoming HTTP connection and the yamux stream.

Rate limiting (per-IP sliding window and per-tunnel token bucket) is enforced before step 2.

### c) TCP Edge Proxy

For each registered TCP tunnel, the server allocates a port from a configured range and spawns a listener. The per-connection flow is identical to HTTP but uses the port-based `tcp_routes` lookup instead of the subdomain-based `http_routes` lookup.

### d) Dashboard

Serves the dashboard UI and a REST API for:

* Listing active sessions and tunnels
* Creating and revoking API tokens (stored in PostgreSQL)
* Viewing a live request capture feed (via Server-Sent Events)
* Viewing audit logs

### e) Prometheus Metrics

Exposes three gauges at `http://<server>:9090/metrics`:

| Metric                          | Description                   |
| ------------------------------- | ----------------------------- |
| `rustunnel_active_sessions`     | Number of connected clients   |
| `rustunnel_active_tunnels_http` | Number of active HTTP tunnels |
| `rustunnel_active_tunnels_tcp`  | Number of active TCP tunnels  |

### f) ACME Certificate Renewal

If `acme_enabled = true` in the server config, a background task periodically checks whether the TLS certificate needs renewal and triggers an ACME challenge. The certificate is hot-swapped into all TLS listeners without restart.

***

## Client Architecture

The client is a single binary (`rustunnel`) with three main concurrent pieces:

```text theme={null}
rustunnel process
│
├── main_loop task (async)
│     select! {
│       Ctrl-C         → clean shutdown
│       ping_interval  → send Ping frame
│       stream_rx.recv → match stream with pending NewConnection
│       ctrl_ws.next   → handle NewConnection / Pong / etc.
│     }
│
├── drive_client_mux task (spawned)
│     loop {
│       poll_next_inbound(yamux conn)
│       → read 16-byte conn_id prefix
│       → send (conn_id, stream) to stream_rx channel
│     }
│
└── proxy tasks (one per connection, spawned)
      tokio::io::copy_bidirectional(
        yamux_stream ↔ TcpStream to local service
      )
```

### State machines

The main loop maintains two buffering maps to handle the race between two asynchronous events that must be correlated:

| Map               | Key       | Value         | Purpose                                         |
| ----------------- | --------- | ------------- | ----------------------------------------------- |
| `pending_conns`   | `conn_id` | `local_addr`  | `NewConnection` arrived before the yamux stream |
| `pending_streams` | `conn_id` | `YamuxStream` | yamux stream arrived before `NewConnection`     |

When both halves arrive (in either order), a proxy task is spawned and both entries are removed.

***

## Control Protocol

Control frames are JSON objects sent as **binary WebSocket messages**. They use serde's `{ "type": "...", ...fields }` envelope.

### Frame types

```text theme={null}
Client → Server                     Server → Client
─────────────────────────────────   ─────────────────────────────────
Auth                                AuthOk
  token: string                       session_id: uuid
  client_version: string              server_version: string
                                    AuthError
                                      message: string

RegisterTunnel                      TunnelRegistered
  request_id: string                  request_id: string
  protocol: http|tcp                  tunnel_id: uuid
  subdomain?: string                  public_url: string
  local_addr: string                  assigned_port?: u16
                                    TunnelError
                                      request_id: string
                                      message: string

Ping                                NewConnection
  timestamp: u64 (ms)                 conn_id: uuid
                                      client_addr: string
Pong                                  protocol: http|tcp
  timestamp: u64 (ms)

                                    Ping / Pong (same as client→server)
```

### Handshake sequence

```text theme={null}
Client                              Server
  │                                   │
  │──── WebSocket upgrade ────────────►│  wss://<server>/_control
  │                                   │
  │──── Auth ─────────────────────────►│
  │        token, client_version       │
  │                                   │  validate token against DB
  │◄─── AuthOk ───────────────────────│
  │        session_id, server_version  │
  │                                   │
  │──── RegisterTunnel ───────────────►│  (one per tunnel)
  │        request_id, protocol, …     │
  │                                   │  allocate subdomain/port
  │◄─── TunnelRegistered ─────────────│
  │        public_url, assigned_port   │
  │                                   │
  │──── WebSocket upgrade ────────────►│  wss://<server>/_data/<session_id>
  │                                   │  (data plane, runs in parallel)
  │                                   │
  │◄══════════════ normal operation ══════════════►│
  │                                   │
  │  every 30 s:                      │
  │──── Ping ─────────────────────────►│
  │◄─── Pong ─────────────────────────│
  │                                   │
  │  on incoming external connection:  │
  │◄─── NewConnection ────────────────│
  │        conn_id, client_addr        │
  │                                   │
  │  (yamux stream arrives separately  │
  │   on the data WebSocket)           │
```

### Heartbeat

* Client sends `Ping` every **30 seconds**.
* Server must respond with `Pong` within **10 seconds**.
* If no `Pong` arrives within the deadline, the client disconnects with `"heartbeat timeout"` and reconnects.

***

## Data Plane — yamux over WebSocket

The data plane uses **yamux** (a stream multiplexer similar to HTTP/2 framing) over the data WebSocket. This allows a single WebSocket connection to carry streams for all proxied connections simultaneously.

### WsCompat adapter

Because yamux requires `futures::io::{AsyncRead, AsyncWrite}` but WebSocket is message-oriented, both server and client use a `WsCompat<S>` wrapper:

```text theme={null}
WebSocket (message-oriented)
         │
    WsCompat<S>
    ┌────────────────────────────────────────┐
    │  Read:  dequeue binary WS frames,       │
    │         present as a byte stream        │
    │  Write: wrap byte slices in binary      │
    │         WS frames and send              │
    └────────────────────────────────────────┘
         │
yamux Connection (stream-oriented)
```

### Mode assignment

yamux uses stream IDs to multiplex; "client" mode uses odd IDs, "server" mode uses even IDs:

| Side   | yamux Mode     | Role                                            |
| ------ | -------------- | ----------------------------------------------- |
| Server | `Mode::Client` | Opens streams, writes first (forces SYN frame)  |
| Client | `Mode::Server` | Accepts inbound streams via `poll_next_inbound` |

<Note>
  This assignment is intentional. yamux 0.13 uses **lazy SYN**: a new stream does not send a SYN frame until the first write. By making the **server** the yamux client (opener+writer), it forces the SYN+DATA immediately, unblocking the actual client's `poll_next_inbound` and avoiding a deadlock.
</Note>

### 16-byte conn\_id prefix

When the server opens a yamux stream for a new proxied connection, it immediately writes the **16-byte raw UUID** (`conn_id.as_bytes()`) into the stream before any proxy data. This allows the client's yamux driver to correlate the stream with the `NewConnection` control frame that named the same `conn_id`.

```text theme={null}
Server yamux driver                 Client yamux driver
  │                                   │
  │  open stream (yamux SYN)          │
  │──────────────────────────────────►│
  │                                   │
  │  write conn_id (16 bytes)         │
  │──────────────────────────────────►│
  │                                   │  read exactly 16 bytes
  │                                   │  conn_id = Uuid::from_bytes(id_bytes)
  │                                   │  send (conn_id, stream) → main loop
  │                                   │
  ├──── proxy data flows both ways ───┤
```

### Server-side duplex pipe

The server does not connect the yamux `Connection` directly to the data WebSocket socket in the session task. Instead, it uses an **in-process loopback pipe**:

```text theme={null}
Session task                   Yamux driver task
  │                                   │
  │  tokio::io::duplex(64 KiB)        │
  │  server_side ↔ client_side        │
  │                                   │
  │  yamux::Connection(server_side)   │  ◄── drives IO
  │                                   │
  │  pipe_client (taken by bridge)    │
  │           │                       │
  │   ┌───────▼────────────────────┐  │
  │   │ copy_bidirectional         │  │
  │   │  pipe_client ↔ data WS     │  │
  │   └────────────────────────────┘  │
```

`copy_bidirectional` bridges `pipe_client` ↔ the data WebSocket transport. The yamux `Connection` reads/writes its internal framing through `server_side`. This decouples session lifecycle from WebSocket I/O.

***

## Per-Connection Flow

Full end-to-end trace for a single HTTP request through the tunnel:

```text theme={null}
Browser          Server (HTTP edge)   TunnelCore   Session task   Yamux driver   Client (main loop)   Client (proxy task)   Local service
  │                    │                  │              │               │                │                    │                  │
  │──── GET /api ──────►│                  │              │               │                │                    │                  │
  │     Host: myapp…    │                  │              │               │                │                    │                  │
  │                    │──── lookup ───────►│              │               │                │                    │                  │
  │                    │◄─── TunnelInfo ────│              │               │                │                    │                  │
  │                    │──── alloc conn_id ─►│              │               │                │                    │                  │
  │                    │──── NewConnection ──────────────►│               │                │                    │                  │
  │                    │                  │              │──── open stream ──────────────►│                │                    │                  │
  │                    │                  │              │──── write conn_id (16 bytes) ──►│                │                    │                  │
  │                    │                  │              │               │  read conn_id   │                │                    │                  │
  │                    │                  │              │               │  send (conn_id, stream) ────────►│                    │                  │
  │                    │                  │              │               │                │──── spawn proxy task ──────────────►│                  │
  │                    │◄══ yamux stream ═══════════════════════════════════════════════════════════════════════════════════════│                  │
  │◄──── 200 OK ────────│◄══════════════════════ bytes flow ═══════════════════════════════════════════════════════════════════►│                  │
```

***

## Concurrency Model

rustunnel uses **Tokio**'s multi-threaded async runtime. All I/O is non-blocking. The key concurrency units are:

### Server-side tasks

| Task                   | Lifetime               | Purpose                                            |
| ---------------------- | ---------------------- | -------------------------------------------------- |
| Control-plane listener | Server lifetime        | Accepts new `/_control` WebSocket connections      |
| Session task           | Per client session     | Runs the control loop for one client               |
| Yamux driver task      | Per client session     | Drives yamux IO, opens streams for new connections |
| Data WebSocket bridge  | Per client session     | `copy_bidirectional(pipe_client ↔ data_ws)`        |
| Edge proxy connection  | Per proxied connection | `copy_bidirectional(edge_socket ↔ yamux_stream)`   |
| HTTP edge              | Server lifetime        | Accepts HTTP/HTTPS connections                     |
| TCP edge listener      | Per TCP tunnel         | Accepts TCP connections                            |
| Dashboard              | Server lifetime        | Serves REST API and SPA                            |
| Metrics                | Server lifetime        | Serves Prometheus endpoint                         |
| ACME renewal           | Server lifetime        | Background cert renewal                            |

### Client-side tasks

| Task         | Lifetime               | Purpose                                        |
| ------------ | ---------------------- | ---------------------------------------------- |
| Main loop    | Session lifetime       | Control protocol, signal handling, heartbeat   |
| Yamux driver | Session lifetime       | Accepts inbound yamux streams, reads conn\_id  |
| Proxy task   | Per proxied connection | `copy_bidirectional(yamux_stream ↔ local_tcp)` |

### Shared state (server)

All server tasks share `Arc<TunnelCore>` which uses lock-free interior mutability:

| Field                 | Type                                          | Purpose                      |
| --------------------- | --------------------------------------------- | ---------------------------- |
| `http_routes`         | `DashMap<String, TunnelInfo>`                 | subdomain → tunnel           |
| `tcp_routes`          | `DashMap<u16, TunnelInfo>`                    | port → tunnel                |
| `sessions`            | `DashMap<Uuid, SessionInfo>`                  | session\_id → session        |
| `pending_conns`       | `DashMap<Uuid, oneshot::Sender<YamuxStream>>` | conn\_id → stream rendezvous |
| `available_tcp_ports` | `Mutex<Vec<u16>>`                             | port pool                    |

***

## TLS and Security

### Certificate management

Two modes are supported:

| Mode       | Config                   | Description                                                                                            |
| ---------- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
| Static PEM | `cert_path` + `key_path` | Pre-existing certificate. Loaded at startup. No auto-renewal.                                          |
| ACME       | `acme_enabled = true`    | Automatic certificate issuance and renewal via Let's Encrypt. Certificate hot-swapped without restart. |

### Authentication

1. The client sends an `Auth` frame with a **bearer token**.
2. The server validates the token against its PostgreSQL database.
3. A failed auth returns `AuthError` and closes the connection. Auth errors are **fatal** on the client — reconnect is not attempted.

### `--insecure` flag

<Warning>When `--insecure` is set, the client installs a custom `ServerCertVerifier` that accepts any certificate. This is intended for local development with self-signed certs only. **Never use in production.**</Warning>

### Rate limiting

Two independent rate limiters run on the server:

| Limiter             | Scope         | Algorithm                            |
| ------------------- | ------------- | ------------------------------------ |
| IP rate limiter     | Per source IP | Sliding window (requests per second) |
| Tunnel rate limiter | Per tunnel    | Token bucket                         |

Both are enforced in the HTTP edge before the request is forwarded.

***

## Metrics and Observability

### Prometheus

The server exposes metrics at `:9090/metrics` in the standard text format:

```text theme={null}
# HELP rustunnel_active_sessions Number of active client sessions
# TYPE rustunnel_active_sessions gauge
rustunnel_active_sessions 3
# HELP rustunnel_active_tunnels_http Number of active HTTP tunnels
# TYPE rustunnel_active_tunnels_http gauge
rustunnel_active_tunnels_http 5
# HELP rustunnel_active_tunnels_tcp Number of active TCP tunnels
# TYPE rustunnel_active_tunnels_tcp gauge
rustunnel_active_tunnels_tcp 2
```

### Structured logging

Both server and client use `tracing` with configurable output. The server supports two formats:

| Format | Config            | Use case                                     |
| ------ | ----------------- | -------------------------------------------- |
| pretty | `format = "text"` | Human-readable terminal output               |
| JSON   | `format = "json"` | Machine-readable log aggregation (e.g. Loki) |

Log level is controlled by `RUST_LOG` (client) or the `logging.level` config key (server).

### Audit log

The server writes append-only JSON audit events to a configurable file:

* Token creation / revocation
* Session connect / disconnect
* Tunnel register / unregister

***

## Component Dependency Graph

```text theme={null}
rustunnel-client
├── rustunnel-protocol   (control frame types)
├── tokio                (async runtime)
├── tokio-tungstenite    (WebSocket client)
├── yamux 0.13           (stream multiplexer)
├── rustls               (TLS — ring provider)
├── clap                 (CLI)
├── serde-json           (frame serialization)
├── indicatif            (spinner / progress bar)
├── console              (terminal colors)
└── tracing              (structured logging)

rustunnel-server
├── rustunnel-protocol   (control frame types)
├── tokio                (async runtime, multi-thread)
├── axum                 (HTTP edge + dashboard API)
├── tokio-tungstenite    (WebSocket server)
├── yamux 0.13           (stream multiplexer)
├── rustls               (TLS — ring provider + ACME)
├── sqlx + PostgreSQL    (token storage + tunnel log)
├── sqlx + SQLite        (captured request storage)
├── dashmap              (lock-free routing table)
├── parking_lot          (port pool mutex)
├── clap                 (CLI)
├── serde-json           (frame + REST serialization)
└── tracing              (structured logging)

rustunnel-mcp  (MCP server)
├── rustunnel-protocol   (control frame types)
├── tokio                (async runtime)
├── reqwest              (REST API client)
├── serde-json           (JSON-RPC serialization)
└── clap                 (CLI)

rustunnel-protocol  (shared library crate)
├── serde + serde-json   (frame serialization)
└── uuid                 (conn_id / session_id / tunnel_id)
```

***

## Crate Structure

```text theme={null}
rustunnel/
├── Cargo.toml                  (workspace)
├── Makefile
├── deploy/
│   ├── Dockerfile
│   ├── docker-compose.yml      (production)
│   ├── docker-compose.local.yml (local dev)
│   ├── server.toml             (production config template)
│   └── rustunnel.service       (systemd unit)
├── dashboard-ui/               (Next.js dashboard UI)
├── docs/
│   ├── client-guide.md
│   ├── api-reference.md
│   ├── architecture.md
│   ├── database.md
│   ├── docker-deployment.md
│   └── mcp-server.md
├── tests/
│   ├── common/mod.rs           (test helpers)
│   └── integration/
│       ├── http_tunnel.rs
│       ├── tcp_tunnel.rs
│       └── reconnect.rs
└── crates/
    ├── rustunnel-protocol/
    │   └── src/
    │       ├── frame.rs        (ControlFrame enum, encode/decode)
    │       └── error.rs
    ├── rustunnel-client/
    │   └── src/
    │       ├── main.rs
    │       ├── config.rs
    │       ├── control.rs
    │       ├── reconnect.rs
    │       ├── proxy.rs
    │       ├── regions.rs
    │       ├── display.rs
    │       └── error.rs
    ├── rustunnel-mcp/
    │   └── src/
    │       └── main.rs         (JSON-RPC over stdio, tool dispatch)
    └── rustunnel-server/
        └── src/
            ├── main.rs
            ├── config.rs
            ├── control/
            │   ├── server.rs
            │   ├── session.rs
            │   └── mux.rs      (WsCompat, MuxSession)
            ├── core/
            │   ├── router.rs   (TunnelCore)
            │   ├── tunnel.rs
            │   ├── limiter.rs
            │   └── ip_limiter.rs
            ├── edge/
            │   ├── http.rs
            │   ├── tcp.rs
            │   └── capture.rs
            ├── dashboard/
            ├── db/
            ├── migrations/
            └── tls/
                ├── mod.rs      (CertManager)
                └── acme.rs
```

***

## See also

<CardGroup>
  <Card title="Self-Hosting" icon="server" href="/docs/guides/self-hosting">
    Production deployment of the rustunnel server on Ubuntu with systemd, TLS, and PostgreSQL.
  </Card>

  <Card title="Load Balancing & Health Checks" icon="scale-balanced" href="/docs/reference/load-balancing">
    How the data plane dispatches across grouped backends with health probes.
  </Card>

  <Card title="P2P Tunnels" icon="arrows-left-right" href="/docs/reference/p2p-tunnels">
    Direct peer-to-peer connections, NAT classification, hole punching, and relay fallback.
  </Card>

  <Card title="Client Guide" icon="terminal" href="/docs/guides/client-guide">
    Every CLI flag and config option, including reconnect and region-selection behavior.
  </Card>
</CardGroup>


# Claude Code Tunnel Plugin — one-command MCP install for rustunnel
Source: https://rustunnel.com/docs/guides/claude-plugin

Install the rustunnel Claude Code tunnel plugin in one command. Claude Code gets six tunnel-management tools via MCP, your token is stored securely, and tunnels are cleaned up automatically on session exit.

The rustunnel **Claude Code tunnel plugin** gives Claude Code full tunnel management without manual MCP configuration. Install the plugin, enter your token, and start asking Claude to expose local services. The plugin is a thin wrapper over the same [MCP server](/docs/guides/mcp-server) any other MCP-compatible agent (Cursor, Windsurf, Claude Desktop, OpenClaw) can use.

## How it works

The plugin bundles a skill definition (agent instructions) and an MCP server configuration. When you enable it, Claude Code:

1. Prompts for your server address and API token (stored securely, entered once)
2. Starts the `rustunnel-mcp` MCP server in the background
3. Makes 6 tunnel management tools available to the agent

***

## Installation

### From the plugin marketplace

```text theme={null}
/plugin install rustunnel
```

### Manual install from source

Clone the repository and point Claude Code at the plugin directory:

```bash theme={null}
git clone https://github.com/joaoh82/rustunnel.git
claude --plugin-dir rustunnel/plugins/claude-code/
```

To load it permanently, add it to your Claude Code settings:

```bash theme={null}
claude plugin install --path rustunnel/plugins/claude-code/
```

During development, use `/reload-plugins` inside Claude Code to pick up file changes without restarting.

***

## Setup

When you enable the plugin, you'll be prompted for three values:

| Prompt         | Hosted example                       | Self-hosted example     |
| -------------- | ------------------------------------ | ----------------------- |
| Server address | `eu.edge.rustunnel.com:4040`         | `localhost:4040`        |
| API URL        | `https://eu.edge.rustunnel.com:8443` | `http://localhost:4041` |
| API token      | `rt_live_abc123...`                  | your admin token        |

<Tip>Get a token at [rustunnel.com](https://rustunnel.com) (hosted) or generate one with `openssl rand -hex 32` for self-hosted servers.</Tip>

These values are persisted by Claude Code — you won't be asked again until you reconfigure.

### Reconfiguring

To change your configuration after installation:

```text theme={null}
/plugin configure rustunnel
```

Run `/reload-plugins` after reconfiguring for changes to take effect.

<Warning>
  The MCP server will not start until all three values are set. If you see a "Missing required user configuration value" error, run `/plugin configure rustunnel` to provide the missing values.
</Warning>

***

## Prerequisites

The `rustunnel` CLI must be installed on your machine. The MCP server spawns it as a subprocess when `create_tunnel` is called.

```bash theme={null}
# Homebrew (macOS/Linux)
brew tap joaoh82/rustunnel
brew install rustunnel

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

***

## Usage

Once installed, just ask Claude:

> "Expose my local server on port 3000."

> "Open an HTTP tunnel to port 8080 with subdomain myapp."

> "Create a TCP tunnel to my PostgreSQL on port 5432."

> "List my active tunnels and close the one on port 3000."

***

## Available tools

| Tool                  | Auth | Description                                         |
| --------------------- | ---- | --------------------------------------------------- |
| `create_tunnel`       | yes  | Open a tunnel and get a public URL                  |
| `close_tunnel`        | yes  | Close a tunnel by UUID                              |
| `list_tunnels`        | yes  | List all active tunnels                             |
| `list_regions`        | no   | Show available server regions                       |
| `get_tunnel_history`  | yes  | View past tunnel activity                           |
| `get_connection_info` | yes  | Get the CLI command string (cloud sandbox fallback) |

See the [MCP Server guide](/docs/guides/mcp-server) for full parameter tables and example responses.

***

## Plugin vs manual MCP setup

| Aspect         | Plugin                      | Manual `.mcp.json`             |
| -------------- | --------------------------- | ------------------------------ |
| Setup          | `/plugin install rustunnel` | Edit config by hand            |
| Token storage  | Secure, entered once        | Hardcoded or passed every call |
| Updates        | `/plugin update rustunnel`  | Manual                         |
| Agent guidance | Built-in skill              | Must add instructions yourself |

***

## Self-hosted servers

The plugin works with self-hosted rustunnel instances. When prompted for the server address and API URL, enter your own server's values instead of the hosted defaults. See the [Self-Hosting guide](/docs/guides/self-hosting) for server setup.

***

## Security

* The API token is stored securely by Claude Code (`sensitive: true`)
* Tokens are transmitted over HTTPS to the rustunnel server
* Tunnel subprocesses are cleaned up when the MCP server exits
* Use `--insecure` only in local development with self-signed certificates

***

## Related pages

<CardGroup>
  <Card title="MCP server" icon="server" href="/docs/guides/mcp-server">
    Full reference for the rustunnel-mcp server the plugin wraps, including all tool parameters.
  </Card>

  <Card title="Agent integration" icon="bot" href="/docs/guides/agent-integration">
    Wire rustunnel into Cursor, Windsurf, Cline, Codex, and other MCP clients.
  </Card>

  <Card title="Self-hosting" icon="terminal" href="/docs/guides/self-hosting">
    Stand up your own rustunnel server to use with the plugin.
  </Card>

  <Card title="rustunnel + Claude Code" icon="bot" href="https://rustunnel.com/ai-tools/claude-code">
    Quick-start version of this page with install one-liners and an agent-ready prompt.
  </Card>
</CardGroup>


# rustunnel CLI Client Guide — every flag, command, and config option
Source: https://rustunnel.com/docs/guides/client-guide

Complete reference for the rustunnel CLI client: installation, authentication, HTTP/TCP/UDP/P2P tunnel commands, live terminal UI, local request inspector, region selection, config file format, and troubleshooting. The companion to the Quickstart and Self-Hosting guides.

This is the complete reference for the rustunnel CLI — every flag, command, and config option, including the live [terminal UI](#terminal-ui) and [request inspector](#request-inspector) shipping in 0.8.3. New to rustunnel? Start with the [Quickstart](/docs/quickstart) for a three-step walkthrough, or the [self-hosting guide](/docs/guides/self-hosting) if you want to run your own server.

## Installation

### From source (recommended)

Requires [Rust](https://rustup.rs/) 1.75 or later.

```bash theme={null}
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
```

Or use the Makefile shortcut:

```bash theme={null}
make deploy-client
```

### Verify

```bash theme={null}
rustunnel --version
```

***

## Quick Start

```bash theme={null}
# 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
```

After connecting, the terminal displays the public URL:

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

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

***

## Configuration File

The client reads `~/.rustunnel/config.yml` automatically. CLI flags always override file values.

### Full example

```yaml theme={null}
# 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
```

### Field reference

| Field                       | Type    | Default       | Description                                                            |
| --------------------------- | ------- | ------------- | ---------------------------------------------------------------------- |
| `server`                    | string  | —             | Tunnel server host:port (e.g. `eu.edge.rustunnel.com:4040`)            |
| `auth_token`                | string  | —             | Authentication token issued by the server                              |
| `insecure`                  | bool    | `false`       | Skip TLS certificate verification (dev only)                           |
| `region`                    | string  | omit          | `auto` (probe nearest), `eu`, `us`, `ap`. Omit for self-hosted setups. |
| `tunnels`                   | map     | `{}`          | Named tunnel definitions (used by `rustunnel start`)                   |
| `tunnels.<name>.proto`      | string  | —             | `http` or `tcp`                                                        |
| `tunnels.<name>.local_port` | integer | —             | Local port to forward                                                  |
| `tunnels.<name>.local_host` | string  | `localhost`   | Local hostname to connect to                                           |
| `tunnels.<name>.subdomain`  | string  | auto-assigned | Requested HTTP subdomain                                               |

***

## Commands

### `setup` — Interactive config wizard

Create (or overwrite) `~/.rustunnel/config.yml` through a guided prompt sequence.

```bash theme={null}
rustunnel setup
```

**Prompts:**

| Prompt         | Default           | Description                                                |
| -------------- | ----------------- | ---------------------------------------------------------- |
| Region         | `auto`            | `auto` (probe nearest), `eu`, `us`, `ap`, or `self-hosted` |
| Auth token     | *(blank)*         | Token issued by the server; leave empty to fill in later   |
| Server address | *(auto-resolved)* | Only prompted when `self-hosted` is selected               |

**Region behavior:**

| Choice             | Server resolution                                |
| ------------------ | ------------------------------------------------ |
| `eu` / `us` / `ap` | Auto-set to `<region>.edge.rustunnel.com:4040`   |
| `auto`             | Probes all regions, picks the nearest by latency |
| `self-hosted`      | Prompts for your server address                  |

**Behaviour:**

* Creates `~/.rustunnel/` if the directory doesn't exist.
* If a config file already exists it is overwritten — a backup is not kept, so copy the old file first if you want to preserve it.
* Writes a commented `tunnels:` block with HTTP and TCP examples so you can see the structure right away.
* Prints `Created:` or `Updated:` with the full path when done.

**Example session (auto region):**

```text theme={null}
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.
```

**Example session (self-hosted):**

```text theme={null}
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.
```

**Generated file (managed):**

```yaml theme={null}
# 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
```

**Generated file (self-hosted):**

```yaml theme={null}
# rustunnel configuration
# Documentation: https://github.com/joaoh82/rustunnel

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

# tunnels:
#   ...
```

After running `setup`, uncomment and fill in the `tunnels:` section then run `rustunnel start`, or use `rustunnel http <port>` / `rustunnel tcp <port>` directly.

***

### `http` — HTTP tunnel

Expose a local HTTP/HTTPS service through the tunnel server.

```bash theme={null}
rustunnel http <port> [options]
```

**Arguments:**

| Argument | Description                             |
| -------- | --------------------------------------- |
| `<port>` | Local TCP port to forward (e.g. `3000`) |

**Options:**

| Flag                   | Default       | Description                                                                      |
| ---------------------- | ------------- | -------------------------------------------------------------------------------- |
| `--subdomain <name>`   | auto-assigned | Request a specific subdomain (e.g. `myapp` → `myapp.eu.edge.rustunnel.com`)      |
| `--server <host:port>` | from config   | Override the server address (bypasses region selection)                          |
| `--token <token>`      | from config   | Override the auth token                                                          |
| `--local-host <host>`  | `localhost`   | Local hostname to forward to                                                     |
| `--region <id>`        | from config   | Region to connect to: `eu`, `us`, `ap`, or `auto`. Ignored if `--server` is set. |
| `--no-reconnect`       | off           | Exit instead of reconnecting on failure                                          |
| `--insecure`           | off           | Skip TLS verification (dev only)                                                 |

**Examples:**

```bash theme={null}
# Expose port 3000 — auto-selects the nearest region
rustunnel http 3000

# Connect to a specific region
rustunnel http 3000 --region eu

# Request a specific subdomain
rustunnel http 3000 --subdomain myapp

# Forward to a non-localhost service
rustunnel http 8080 --local-host 192.168.1.10

# One-shot connection (exit on disconnect instead of reconnecting)
rustunnel http 3000 --no-reconnect

# Use an explicit server address (bypasses region selection)
rustunnel http 3000 --server tunnel.example.com:9000 --token rt_live_abc123
```

***

### `tcp` — TCP tunnel

Expose any raw TCP service (database, SSH, game server, etc.).

```bash theme={null}
rustunnel tcp <port> [options]
```

**Arguments:**

| Argument | Description               |
| -------- | ------------------------- |
| `<port>` | Local TCP port to forward |

**Options:** Same as `http` except `--subdomain` has no effect for TCP tunnels. `--region` still works.

**Examples:**

```bash theme={null}
# Expose a local PostgreSQL instance
rustunnel tcp 5432

# Expose SSH on a non-standard port
rustunnel tcp 2222 --local-host 10.0.0.5
```

The server assigns a random public port from its configured TCP port range. The public address is displayed in the startup box.

***

### `start` — Multi-tunnel mode

Start all tunnels defined in a config file simultaneously.

```bash theme={null}
rustunnel start [--config <path>]
```

**Options:**

| Flag                  | Default                   | Description           |
| --------------------- | ------------------------- | --------------------- |
| `-c, --config <path>` | `~/.rustunnel/config.yml` | Path to a config file |

**Example:**

```bash theme={null}
# Use default config file
rustunnel start

# Use a custom config file
rustunnel start --config /etc/rustunnel/production.yml
```

`start` always reconnects automatically (equivalent to running each tunnel without `--no-reconnect`). At least one tunnel must be defined in the config file or the command exits with an error.

***

### Multiple backends (load balancing)

When `start` is given two or more tunnels with the same `(group, group_key)`, the server treats them as one logical pool — inbound traffic is dispatched to a healthy member at random. This is the path for running a hot-spare backend, scaling out a service horizontally behind a single subdomain, or doing zero-downtime rollouts.

Add the load-balancing fields to each pool member's tunnel definition:

```yaml theme={null}
server: tunnel.example.com:4040
auth_token: "your-token"

tunnels:
  a:
    proto: http
    local_port: 3000
    subdomain: pool
    group: web
    group_key: shared-secret-for-this-pool
    health_check:
      type: tcp
      # Optional: when this group goes 0/N healthy, the server POSTs a
      # group_zero_healthy alert to this URL. Per-tenant — independent
      # of any operator-side webhook configured on the edge.
      alert_webhook: "https://hooks.slack.com/services/my-team/..."
```

Run a second client (on the same or a different host) with `local_port: 3001`, the same `subdomain`, and the same `(group, group_key)`. Both clients register as members of the same pool; public connections to `pool.tunnel.example.com` are dispatched at random across them.

<Note>
  Load balancing requires `[load_balancing] enabled = true` in the server's `server.toml`. When the flag is `false` (the default), the client's `group` / `group_key` / `health_check` fields are accepted but ignored — both clients try to register as solo tunnels and the second one fails with `subdomain '...' is already in use`.
</Note>

#### Quick smoke test

End-to-end validation with two backends sharing one subdomain.

<Steps>
  <Step title="Build the client from source">
    ```bash theme={null}
    git clone https://github.com/joaoh82/rustunnel
    cd rustunnel
    cargo build --release -p rustunnel-client
    ```
  </Step>

  <Step title="Drop a config that opts into a group">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Start backend A and client A">
    ```bash theme={null}
    # Terminal 1 — backend A
    python3 -m http.server 3000

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

  <Step title="Start backend B and client B">
    Use a second config file that's identical except for `local_port: 3001`.

    ```bash theme={null}
    # Terminal 3 — backend B
    python3 -m http.server 3001

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

  <Step title="Hammer the public URL">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Validate failover">
    Kill one of the local backends (Ctrl-C on its `python3` process). 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.
  </Step>
</Steps>

For the full reference (config field meanings, behaviour rules, observability series, limitations) see [Load Balancing & Health Checks](/docs/reference/load-balancing).

***

### `token create` — API token management

Create a new API token via the server's dashboard REST API. Requires admin credentials.

```bash theme={null}
rustunnel token create --name <label> [options]
```

**Options:**

| Flag                    | Default          | Description                                   |
| ----------------------- | ---------------- | --------------------------------------------- |
| `--name <label>`        | —                | Human-readable label for the token (required) |
| `--server <host:port>`  | `localhost:4040` | Dashboard server address                      |
| `--admin-token <token>` | —                | Admin token for authentication                |

**Example:**

```bash theme={null}
rustunnel token create \
  --name "production-server" \
  --server tunnel.example.com:4040 \
  --admin-token admin_secret_here
```

**Output:**

```text theme={null}
Token created:
  id:    f47ac10b-58cc-4372-a567-0e02b2c3d479
  token: rt_live_abc123xyz...
  label: production-server
```

<Warning>Copy the `token` value — it is shown only once. Add it to your config file as `auth_token`.</Warning>

***

## Flags Reference

| Flag                    | Commands                                 | Description                                                                |
| ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------- |
| `--server <host:port>`  | http, tcp                                | Tunnel server address (bypasses region selection)                          |
| `--token <token>`       | http, tcp                                | Auth token (overrides config; also read from `RUSTUNNEL_TOKEN`)            |
| `--subdomain <name>`    | http                                     | Requested HTTP subdomain                                                   |
| `--local-host <host>`   | http, tcp                                | Local hostname (default: `localhost`)                                      |
| `--region <id>`         | http, tcp                                | Region: `eu`, `us`, `ap`, or `auto`. Ignored if `--server` is set.         |
| `--no-reconnect`        | http, tcp                                | Exit on failure instead of reconnecting                                    |
| `--insecure`            | http, tcp                                | Skip TLS certificate verification                                          |
| `--json`                | http, tcp, udp, p2p, start, token create | Emit machine-readable NDJSON events on stdout instead of human output      |
| `--no-tui`              | http, tcp, udp, p2p, start               | Disable the full-screen terminal UI; print one line per request instead    |
| `--inspect-port <port>` | http, tcp, udp, p2p, start               | Port for the local web inspector (default `4040`; `0` picks any free port) |
| `--no-inspect`          | http, tcp, udp, p2p, start               | Disable the local web inspector                                            |
| `-c, --config <path>`   | start                                    | Config file path                                                           |
| `--name <label>`        | token create                             | Token label (required)                                                     |
| `--admin-token <token>` | token create                             | Admin token for dashboard API                                              |
| `--version`             | all                                      | Print version and exit                                                     |
| `--help`                | all                                      | Print help and exit                                                        |

`setup` takes no flags — all input is collected interactively.

***

## Region Selection

rustunnel can connect to multiple edge servers in different geographic regions. The region selection logic follows this priority order:

1. **`--server <host:port>`** — explicit server address always wins; region logic is skipped entirely.
2. **`--region <id>`** — connect directly to the named region without probing.
3. **`region: auto`** (config file or `--region auto`) — probe all regions in parallel and pick the nearest.
4. **No region preference** — use `server:` from config as-is (backward compatible with self-hosted setups).

### Available regions (hosted service)

| Region ID | Location      | Server                       |
| --------- | ------------- | ---------------------------- |
| `eu`      | Helsinki, FI  | `eu.edge.rustunnel.com:4040` |
| `us`      | Hillsboro, OR | `us.edge.rustunnel.com:4040` |
| `ap`      | Singapore     | `ap.edge.rustunnel.com:4040` |

### Auto-select output

When `region: auto` is active, the client probes all regions by TCP connect time and prints:

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

Unreachable regions time out after 3 seconds and are assigned a 10-second penalty so they never win the selection.

### Region list refresh

The region list is cached at `~/.rustunnel/regions.json` for 24 hours. On expiry the client fetches a fresh list from `GET https://<host>:8443/api/regions`; if that fails it falls back to the hardcoded list compiled into the binary.

***

## Reconnection Behavior

By default, `rustunnel` reconnects automatically when the connection drops. The retry delay follows an **exponential backoff** schedule:

| Attempt | Delay        |
| ------- | ------------ |
| 1       | \~1 s        |
| 2       | \~2 s        |
| 3       | \~4 s        |
| 4       | \~8 s        |
| …       | …            |
| n≥6     | \~60 s (max) |

Each delay has ±20% random jitter to prevent thundering-herd reconnects when a server restarts.

```text theme={null}
  Reconnecting in 2.3s (attempt 2)…
  Reconnecting in 5.1s (attempt 3)…
```

### Fatal errors (no reconnect)

The following errors cause an immediate exit — retrying would not help:

* **Auth failed** — invalid or revoked token. Fix: create a new token at [rustunnel.com](https://rustunnel.com) (Dashboard → API Keys) and update your config.
* **Config error** — missing required fields. Fix: check your `~/.rustunnel/config.yml`.

### Disabling reconnect

Use `--no-reconnect` for scripting, CI, or when you want manual control:

```bash theme={null}
rustunnel http 3000 --no-reconnect || echo "Tunnel exited"
```

***

## Terminal Output

When stdout is a terminal, the client takes over the screen with a live UI.
Otherwise — piped output, CI, `--no-tui`, or `--json` — it falls back to the
line-based output described further down.

### Terminal UI

<Frame>
  <img alt="rustunnel full-screen terminal UI showing session status, tunnel health, traffic counters, and request log" />
</Frame>

```text theme={null}
┌ rustunnel ───────────────────────────────────────────────────────────────────┐
│Session  ● online                    Server   eu.edge.rustunnel.com:4040      │
│Uptime   00:12:43                    Region   eu · 57ms                       │
│Version  0.8.3                       Inspect  http://127.0.0.1:4040           │
└──────────────────────────────────────────────────────────────────────────────┘
┌ Tunnels ─────────────────────────────────────────────────────────────────────┐
│HTTP   web    http://bb176fb6.eu.edge.rustunnel.com  → localhost:3000  ● healthy│
└──────────────────────────────────────────────────────────────────────────────┘
┌ Traffic ─────────────────────────────────────────────────────────────────────┐
│Conns    2 open · 27 total    Requests 1204                        req/s       │
│Traffic  ↑ 1.2 MB  ↓ 830.0 kB    Latency  p50 6ms · p90 41ms      ▁▂▃▅▂▁▃▂    │
└──────────────────────────────────────────────────────────────────────────────┘
┌ Requests ────────────────────────────────────────────────────────────────────┐
│23:21:54 GET     /style.css                    200   3 ms    95.99.57.76:51224│
│23:21:53 POST    /api/items                    201  18 ms    95.99.57.76:51223│
│23:21:53 GET     /missing                      404   2 ms    95.99.57.76:51222│
└──────────────────────────────────────────────────────────────────────────────┘
q quit  ↑↓ scroll  f pause  c clear  l logs
```

* **Session** — connection state, uptime, client version, edge server, region and live control-plane latency (measured from the keepalive round-trip), and the local inspector URL.
* **Tunnels** — one row per tunnel with its public URL, local target, and health when a `health_check` is configured.
* **Traffic** — open/total connections, bytes each way, p50/p90 request duration, and a requests-per-second sparkline.
* **Requests** — live log of every HTTP request: time, method, path, status, duration, and the public client address. Replayed requests are marked `↻`.

Keys:

| Key                  | Action                                   |
| -------------------- | ---------------------------------------- |
| `q`, `Esc`, `Ctrl-C` | Quit (closes the tunnel)                 |
| `↑` `↓` / `k` `j`    | Scroll the request log                   |
| `PgUp` / `PgDn`      | Scroll by page                           |
| `g` / `G`            | Jump to newest / oldest                  |
| `f`                  | Pause or resume following new requests   |
| `c`                  | Clear the captured requests              |
| `l`                  | Toggle the log pane (client diagnostics) |

Only HTTP tunnels produce request rows. TCP and UDP tunnels are opaque byte streams, so they show connection and traffic counters only.

### Line mode

With `--no-tui`, a non-terminal stdout, or `--json`, output stays line-based.

While establishing the connection a spinner is shown:

```text theme={null}
⠙ Connecting to tunnel server…
⠹ Authenticating…
⠼ Registering tunnels…
```

Once all tunnels are registered, a bordered box appears:

```text theme={null}
╭────────────────────────────────────────────────────────────╮
│                         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.

  Inspect http://127.0.0.1:4040
```

Color coding:

* Protocol label — **bold yellow**
* Tunnel name — dim
* Public URL — **bold green**
* Border — cyan

Requests then stream one per line as they arrive:

```text theme={null}
23:21:54    GET /style.css                     200 3ms
23:21:53   POST /api/items                     201 18ms
23:21:53    GET /missing                       404 2ms
```

### JSON output (`--json`)

With `--json`, the spinner and startup box are suppressed and stdout instead carries NDJSON — one JSON event object per line — for scripts and AI agents:

```json theme={null}
{"event":"tunnel_ready","protocol":"http","public_url":"https://myapp.tunnel.example.com","local_port":3000,"local_host":"localhost","tunnel_id":"6f9a…","name":"myapp"}
```

Events: `inspector_ready` (`url`; emitted once at startup when the request inspector is enabled), `tunnel_ready` (includes `public_addr` host:port for tcp/udp), `reconnecting` (`attempt`, `reason`, `delay_secs`), `reconnected`, `error` (`code`, `message`, `hint`; exit code 1 follows), and `token_created` (for `token create --json`). Diagnostics still go to stderr.

A `--json` session that also runs the inspector emits it first, so a script can pick the port up before any traffic arrives:

```json theme={null}
{"event":"inspector_ready","url":"http://127.0.0.1:4040"}
{"event":"tunnel_ready","protocol":"http","public_url":"https://myapp.tunnel.example.com","local_port":3000,"local_host":"localhost"}
```

### Graceful shutdown

Press `Ctrl-C` to cleanly close the tunnel and exit. The control WebSocket is closed before the process exits. In the terminal UI, `q` and `Esc` do the same.

***

## Request Inspector

Every tunnel session also starts a small web inspector on loopback, printed at startup and shown in the terminal UI:

```text theme={null}
Inspect http://127.0.0.1:4040
```

Open it to browse everything that flowed through the tunnel. See the dedicated [Request Inspector](/docs/guides/request-inspector) guide for the full walkthrough.

<Frame>
  <img alt="rustunnel local web request inspector showing request list, detail tabs, and Replay button" />
</Frame>

* **Request list** — live-updating, with method, path, status, and duration. Filter by method, path, or status.
* **Detail view** — Summary (bodies), Headers (full request and response headers), and Raw (the reconstructed HTTP messages).
* **Replay** — re-issue any captured request against your local service without the original caller doing anything. Handy for webhooks: trigger once, then iterate against the same payload. Replayed requests appear in the list marked `replay`.

### Scope and limits

* Captures **HTTP tunnels only**. TCP and UDP tunnels are raw byte streams; they contribute connection and traffic counters but no request entries.
* Keeps the **last 500 requests in memory**, per process. Nothing is written to disk and nothing survives a restart.
* Bodies are captured up to **64 KB each**; larger ones are marked truncated (the reported size is still exact). A truncated request body cannot be replayed byte-for-byte.
* WebSocket and other upgraded connections are recorded as their handshake (`101`); the frames afterwards are not parsed.

### Configuration

| Flag                    | Effect                                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--inspect-port <port>` | Bind a specific port (default `4040`). If it is taken, the next free port is used and the real URL is displayed. |
| `--no-inspect`          | Disable the inspector entirely.                                                                                  |

Because the port can shift when the preferred one is taken, always read the actual URL rather than assuming `4040` — from the terminal UI header, the line under the startup box, or the `inspector_ready` event in `--json` mode.

The inspector binds `127.0.0.1` only and has no authentication, so treat it as local-only — captured payloads may contain credentials, tokens, and personal data. Use `--no-inspect` on shared or multi-user machines.

***

## Environment Variables

| Variable          | Description                                                                                                                                                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `RUST_LOG`        | Log level filter (e.g. `debug`, `info`, `warn`, `rustunnel=debug`). Default: `warn`.                                                                                                                                                                                     |
| `RUSTUNNEL_TOKEN` | Auth token for the `http`, `tcp`, `udp`, and `p2p` commands, used when `--token` is not passed (takes precedence over the config file; empty values are ignored). `start` reads tokens from the config file only, and `token create` authenticates with `--admin-token`. |

**Examples:**

```bash theme={null}
# Enable debug logging for all crates
RUST_LOG=debug rustunnel http 3000

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

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

<Note>Log output goes to **stderr**. Normal tunnel output (terminal UI / line mode, reconnect messages) goes to **stdout**.</Note>

***

## Error Reference

| Error                                                   | Cause                                            | Fix                                                                                                                                         |
| ------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `config error: server address is required`              | No `--server` flag and no config file            | Add `server:` to `~/.rustunnel/config.yml` or pass `--server`                                                                               |
| `auth failed: <message>`                                | Token invalid or revoked                         | Create a new token at [rustunnel.com](https://rustunnel.com) (Dashboard → API Keys) or with `rustunnel token create` for self-hosted setups |
| `tunnel error: <message>`                               | Subdomain already in use or server limit reached | Use a different `--subdomain` or wait                                                                                                       |
| `connection error: control WS: …`                       | Can't reach the server                           | Check network, firewall, and server address                                                                                                 |
| `connection error: heartbeat timeout`                   | Server stopped responding to pings               | Transient — reconnect loop will retry                                                                                                       |
| `connection error: timeout waiting for server response` | Auth/registration timed out (10 s)               | Check server health; may be overloaded                                                                                                      |
| `no tunnels defined in config file`                     | `rustunnel start` with an empty `tunnels:` map   | Add at least one tunnel to the config                                                                                                       |

***

## Troubleshooting

### Tunnel connects but requests don't arrive

* Verify your local service is running and listening: `curl http://localhost:<port>`
* Check `--local-host` if forwarding to a non-localhost address

### Certificate verification failed

If your server uses a self-signed certificate (common for local/staging environments), use `--insecure`:

```bash theme={null}
rustunnel http 3000 --insecure
```

<Warning>**Never use `--insecure` in production** — it disables all TLS certificate checks.</Warning>

### Subdomain already taken

The server returns `tunnel error: subdomain already in use`. Either:

* Omit `--subdomain` to get an auto-assigned subdomain, or
* Choose a different name: `--subdomain myapp-dev`

### Debugging connection issues

Enable verbose logging to see full protocol traces:

```bash theme={null}
RUST_LOG=debug rustunnel http 3000 2>&1 | tee rustunnel.log
```

Key log messages to look for:

| Message                                  | Meaning                                    |
| ---------------------------------------- | ------------------------------------------ |
| `authenticated session_id=...`           | Auth succeeded                             |
| `tunnel registered public_url=...`       | Tunnel is active                           |
| `data WebSocket connected`               | Data plane is ready                        |
| `new connection from server conn_id=...` | Incoming proxied request                   |
| `yamux data conn error`                  | Data-plane transport error                 |
| `heartbeat timeout`                      | Server stopped responding — will reconnect |

### Multiple tunnels on the same server

Use `rustunnel start` with a config file to open all tunnels over a single control connection:

```yaml theme={null}
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 theme={null}
rustunnel start
```

***

## Related pages

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Expose your first local port in three steps with the hosted service.
  </Card>

  <Card title="Request Inspector" icon="magnifying-glass" href="/docs/guides/request-inspector">
    Browse and replay HTTP traffic on localhost:4040 while a tunnel is live.
  </Card>

  <Card title="Self-Hosting Guide" icon="server" href="/docs/guides/self-hosting">
    Run your own rustunnel server with systemd, TLS, and PostgreSQL.
  </Card>

  <Card title="Load Balancing & Health Checks" icon="route" href="/docs/reference/load-balancing">
    Pool multiple backends behind one subdomain with automatic failover.
  </Card>
</CardGroup>


# Deploy rustunnel-server with Docker — local dev or VPS production
Source: https://rustunnel.com/docs/guides/docker-deployment

Deploy the rustunnel tunnel server with Docker. Covers a local-development setup with a self-signed certificate and a production VPS deployment with a real domain and Let's Encrypt TLS — pair with the systemd-based self-hosting guide.

This guide walks through how to **deploy rustunnel-server with Docker**, in two scenarios:

* **[Scenario A — Local development](#scenario-a-local-development)**: run the server on your laptop using a self-signed certificate.
* **[Scenario B — VPS production](#scenario-b-vps-production)**: deploy on a cloud server with a real domain and Let's Encrypt TLS.

For a non-Docker, systemd-based production deployment see the [self-hosting guide](/docs/guides/self-hosting). For the architecture behind the server see the [architecture reference](/docs/guides/architecture).

***

## Prerequisites

| Tool           | Version     | Notes                                                     |
| -------------- | ----------- | --------------------------------------------------------- |
| Docker Engine  | 24+         | [Install docs](https://docs.docker.com/engine/install/)   |
| Docker Compose | v2 (plugin) | Bundled with Docker Desktop; `docker compose` (no hyphen) |
| Git            | any         | To clone the repository                                   |

Clone the repository once:

```bash theme={null}
git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel
```

***

## How the Docker image works

The `deploy/Dockerfile` is a three-stage build:

1. **`ui-builder`** — installs Node 20, runs `next build` on the dashboard UI, and produces the static export under `out/`.
2. **`builder`** — compiles the Rust server. The `out/` directory is copied into `crates/rustunnel-server/src/dashboard/assets/` so `rust-embed` can bake it into the binary at compile time.
3. **`runtime`** — minimal `debian:bookworm-slim` image containing only the server binary and `ca-certificates`.

<Note>Because both the UI and the Rust binary are built inside Docker you do **not** need Node.js or Rust installed on the host to build or run the image.</Note>

***

## Scenario A — Local development

Use this when you want to run a full server stack on your laptop for testing or development.

### 1 — Generate a self-signed certificate

```bash theme={null}
mkdir -p /tmp/rustunnel-certs

openssl req -x509 -newkey rsa:2048 \
  -keyout /tmp/rustunnel-certs/key.pem \
  -out    /tmp/rustunnel-certs/cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost"
```

The compose file mounts this directory into the container at `/certs`.
To use a different path, set the `CERT_DIR` environment variable before running compose.

### 2 — Build the image

```bash theme={null}
make docker-build
# equivalent: docker build -f deploy/Dockerfile -t rustunnel-server:latest .
```

The first build takes several minutes (Rust + Node.js compilation).
Subsequent builds use Docker layer caching and are much faster unless `Cargo.lock` or `package-lock.json` change.

### 3 — Start the server

```bash theme={null}
docker compose -f deploy/docker-compose.local.yml up
```

Add `-d` to detach:

```bash theme={null}
docker compose -f deploy/docker-compose.local.yml up -d
```

### 4 — Verify it is running

```bash theme={null}
# Health check (HTTP — no TLS required for dashboard in local mode)
curl http://localhost:4041/api/status

# Open the dashboard in a browser
open http://localhost:4041
```

### 5 — Connect a client

```bash theme={null}
# Expose a local service running on port 3000
rustunnel http 3000 \
  --server localhost:4040 \
  --token dev-secret-change-me \
  --insecure
```

<Warning>`--insecure` skips TLS verification. Required for self-signed certificates. **Never** use this flag against a production server.</Warning>

### 6 — Stop the server

```bash theme={null}
docker compose -f deploy/docker-compose.local.yml down
```

### Port reference (local)

| Port          | Purpose                                        |
| ------------- | ---------------------------------------------- |
| `4040`        | Control-plane WebSocket — clients connect here |
| `4041`        | Dashboard UI and REST API                      |
| `8080`        | HTTP edge (tunnel ingress, redirects to HTTPS) |
| `8443`        | HTTPS edge (TLS-terminated tunnel ingress)     |
| `20000–20099` | TCP tunnel range                               |

### Reaching HTTP tunnel URLs locally

HTTP tunnels use subdomains (e.g. `http://abc123.localhost:8080`).
Browsers do not resolve `*.localhost` by default. Two options:

**Option A — curl with a Host header (no setup)**

```bash theme={null}
curl -v -H "Host: abc123.localhost" http://localhost:8080/
```

**Option B — wildcard DNS via dnsmasq (macOS)**

```bash theme={null}
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
```

Then visit `http://abc123.localhost:8080` in the browser.

***

## Scenario B — VPS production

Use this when you have a cloud server (Ubuntu 22.04 or later recommended) with a public IP address.

### Assumptions

| Item         | Example value                                          |
| ------------ | ------------------------------------------------------ |
| Domain       | `edge.rustunnel.com`                                   |
| Wildcard DNS | `*.edge.rustunnel.com → <server public IP>`            |
| TLS          | Let's Encrypt via Certbot + Cloudflare DNS challenge   |
| OS           | Ubuntu 22.04 LTS                                       |
| PostgreSQL   | Managed instance or self-hosted (required — see below) |

<Note>
  **PostgreSQL is required.** The server uses PostgreSQL to store API tokens and the tunnel audit log. You may run PostgreSQL on the same VPS or use a managed service (e.g. Supabase, Neon, AWS RDS, DigitalOcean Managed Databases). Set the connection URL in `deploy/server.toml` under `[database] url`.
</Note>

Set up the wildcard DNS record with your DNS provider before continuing.
Both `edge.rustunnel.com` (bare) and `*.edge.rustunnel.com` (wildcard) must resolve to your server IP — the wildcard is required so HTTP tunnel subdomains work.

### 1 — Install dependencies on the VPS

```bash theme={null}
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
```

### 2 — Clone the repository

```bash theme={null}
git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel
```

### 3 — Obtain TLS certificates

Create the Cloudflare credentials file:

```bash theme={null}
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
```

Request the certificate (bare domain + wildcard):

```bash theme={null}
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 PEM files to:

```text theme={null}
/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem
/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem
```

Certbot installs a systemd timer for automatic renewal — no further action needed.

### 4 — Configure the server

Generate a strong admin token:

```bash theme={null}
openssl rand -hex 32
```

Edit `deploy/server.toml` — set **at minimum**:

```toml theme={null}
[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
# Failed auth attempts per source IP per minute before rejection (0 = off).
max_failed_auth_per_minute = 10
```

The file is mounted read-only into the container.

### 5 — Grant the container access to the certificates

The container runs as a non-root user (`rustunnel`). Certbot sets restrictive permissions on the `live/` and `archive/` directories by default:

```bash theme={null}
# Allow read access to cert directories
chmod 755 /etc/letsencrypt/{live,archive}
chmod 640 /etc/letsencrypt/live/edge.rustunnel.com/*.pem
chmod 640 /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
```

<Tip>If you prefer not to relax Certbot permissions, copy the certs to a dedicated directory and set up a Certbot post-hook to refresh the copies after each renewal.</Tip>

### 6 — Build the Docker image

```bash theme={null}
docker build -f deploy/Dockerfile -t rustunnel-server:latest .
```

### 7 — Start the server

```bash theme={null}
docker compose -f deploy/docker-compose.yml up -d
```

The `docker-compose.yml` mounts:

* `./server.toml` → `/etc/rustunnel/server.toml` (read-only)
* `/etc/letsencrypt` is **not** mounted by default — add the line below to the server service's `volumes` section before starting:

```yaml theme={null}
volumes:
  - ./server.toml:/etc/rustunnel/server.toml:ro
  - /etc/letsencrypt:/etc/letsencrypt:ro   # ← add this
  - rustunnel-data:/var/lib/rustunnel
```

### 8 — Open firewall ports

```bash theme={null}
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"
ufw allow 20000:20099/tcp comment "rustunnel TCP tunnels"
```

<Note>Port 9090 only needs to be open if you have an external Prometheus scraper. It is safe to leave it closed if you are running Prometheus on the same host (it reaches the metrics endpoint over the Docker bridge network).</Note>

### 9 — Verify the deployment

```bash theme={null}
# Health check
curl https://edge.rustunnel.com:8443/api/status

# Prometheus metrics
curl -s http://localhost:9090/metrics

# Tail logs
docker compose -f deploy/docker-compose.yml logs -f rustunnel-server
```

### 10 — Connect a client

```bash theme={null}
rustunnel http 3000 \
  --server edge.rustunnel.com:4040 \
  --token YOUR_ADMIN_TOKEN
```

### Port reference (production)

| Port          | Purpose                                                         |
| ------------- | --------------------------------------------------------------- |
| `80`          | HTTP edge (redirects to HTTPS; handles ACME HTTP-01 if enabled) |
| `443`         | HTTPS edge (TLS-terminated tunnel ingress)                      |
| `4040`        | Control-plane WebSocket — clients connect here                  |
| `8443`        | Dashboard UI and REST API                                       |
| `9090`        | Prometheus metrics (`/metrics`)                                 |
| `20000–20099` | TCP tunnel range (configurable via `tcp_port_range`)            |

***

## Optional: monitoring stack (Prometheus + Grafana)

Both compose files expose the metrics endpoint to the `rustunnel` Docker network.
The Prometheus service in `docker-compose.yml` scrapes it automatically.

```bash theme={null}
# Start server + Prometheus + Grafana
docker compose -f deploy/docker-compose.yml --profile monitoring up -d

# URLs
# Grafana:    http://<host>:3000   (admin / changeme — change GF_SECURITY_ADMIN_PASSWORD)
# Prometheus: http://<host>:9090
```

To change the Grafana admin password before starting, set the environment variable:

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

***

## Useful make targets

| Target                       | Description                         |
| ---------------------------- | ----------------------------------- |
| `make docker-build`          | Build the Docker image              |
| `make docker-run`            | Start the server container only     |
| `make docker-run-monitoring` | Start server + Prometheus + Grafana |
| `make docker-logs`           | Tail server container logs          |
| `make docker-stop`           | Stop and remove all containers      |

***

## Updating

Pull the latest code and rebuild:

```bash theme={null}
git pull
docker build -f deploy/Dockerfile -t rustunnel-server:latest .
docker compose -f deploy/docker-compose.yml up -d --force-recreate rustunnel-server
```

The `--force-recreate` flag restarts the container with the new image while
leaving the `rustunnel-data` volume (SQLite captured-request data) intact.
PostgreSQL data lives outside the container and is unaffected by container
updates.

***

## Troubleshooting

### Container exits immediately

```bash theme={null}
docker compose -f deploy/docker-compose.yml logs rustunnel-server
```

Common causes:

* **Config not mounted** — ensure `deploy/server.toml` exists and the volume path is correct.
* **Cert files not readable** — check permissions on `/etc/letsencrypt/` (see step 5).
* **Port already in use** — check `ss -tlnp | grep -E '80|443|4040|8443'`.

### Dashboard shows "dashboard assets not found"

The dashboard assets were not embedded at compile time. This happens if you built the Rust binary before running `npm run build` (or outside Docker). Rebuild the image with `docker build` — the multi-stage Dockerfile handles the UI build automatically.

### `--insecure` flag required even in production

This means the client is connecting to a server with a self-signed cert. Verify that the cert paths in `server.toml` point to the Let's Encrypt PEM files and that those files are accessible inside the container.

### Prometheus shows no data

Check that `deploy/prometheus.yml` targets `rustunnel-server:9090` and that both services are on the same Docker network (`rustunnel`). The metrics endpoint is not exposed on the host by default — Prometheus reaches it over the bridge network.

***

## Related pages

<CardGroup>
  <Card title="Self-hosting" icon="server" href="/docs/guides/self-hosting">
    Deploy the server without Docker, using systemd, on a production VPS.
  </Card>

  <Card title="Architecture" icon="network" href="/docs/guides/architecture">
    The control plane, data plane, and subsystems running inside the container.
  </Card>

  <Card title="Client guide" icon="terminal" href="/docs/guides/client-guide">
    Configure the rustunnel CLI to connect to your Dockerized server.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Open your first tunnel in under five minutes.
  </Card>
</CardGroup>


# MCP Tunnel Server — Let Claude Code, Cursor, and any MCP agent manage tunnels
Source: https://rustunnel.com/docs/guides/mcp-server

rustunnel-mcp is a Model Context Protocol (MCP) tunnel server: Claude Code, Cursor, Claude Desktop, OpenClaw, and any MCP-compatible agent can create, list, and close tunnels with six dedicated tools. No manual setup required.

The `rustunnel-mcp` binary is the **MCP tunnel server** for rustunnel. It implements the [Model Context Protocol](https://spec.modelcontextprotocol.io) over stdio, letting AI agents — Claude Code, Cursor, GPT-4o, Gemini, Claude Desktop, OpenClaw, and any other MCP-compatible client — manage tunnels with six dedicated tools and no manual setup. For Claude Code specifically, the [Claude Code plugin](/docs/guides/claude-plugin) wraps this same server in a one-command install.

<Info>
  **Just want to wire rustunnel into your harness?** See the [agent integration guide](/docs/guides/agent-integration) for copy-paste config for Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Cline, and generic MCP clients, plus a one-command installer (`integrations/install.sh`). This page is the deeper reference for the server and its tools.
</Info>

***

## How it works

MCP is a standard for connecting AI agents to external tools. The agent sends JSON-RPC calls to the MCP server; the server translates them into REST API calls and CLI commands.

```text theme={null}
AI Agent ──── MCP (stdio) ────▶ rustunnel-mcp
                                    │               │
                              spawns rustunnel   calls /api/*
                              CLI subprocess     (REST API)
                                    │               │
                                    └───────────────▼
                                          rustunnel-server
```

<Note>
  Tunnels are established via a persistent WebSocket connection (the control plane on port 4040), not via a REST call. The MCP server handles this by spawning the `rustunnel` CLI as a subprocess when `create_tunnel` is called.
</Note>

***

## Installation

Build from source (included in the workspace):

```bash theme={null}
make release-mcp
# Produces: target/release/rustunnel-mcp

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

Or build without the dashboard UI step:

```bash theme={null}
cargo build --release -p rustunnel-mcp
```

***

## Configuration

`rustunnel-mcp` takes two flags:

| Flag         | Default                 | Description                                                       |
| ------------ | ----------------------- | ----------------------------------------------------------------- |
| `--server`   | `localhost:4040`        | Control-plane address forwarded to the `rustunnel` CLI            |
| `--api`      | `http://localhost:4041` | Dashboard REST API base URL for tunnel queries                    |
| `--insecure` | false                   | Skip TLS certificate verification (local dev / self-signed certs) |

***

## Connecting an AI agent

### Using the hosted server (eu.edge.rustunnel.com)

The fastest way to get started. You need an auth token — create a free account at [rustunnel.com](https://rustunnel.com) and generate one from **Dashboard → API Keys → Create token**.

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

**Claude Code (plugin — recommended)** — install the plugin for zero-config setup:

```text theme={null}
/plugin install rustunnel
```

Then configure your server details:

```text theme={null}
/plugin configure rustunnel
```

You'll be prompted for your server address, API URL, and token. These are stored securely and persist across sessions. To reconfigure later, run `/plugin configure rustunnel` again, then `/reload-plugins`.

See the [Claude Code Plugin guide](/docs/guides/claude-plugin) for full details.

**Claude Code (manual `.mcp.json`)** — add to your project's `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "rustunnel": {
      "command": "rustunnel-mcp",
      "args": [
        "--server", "eu.edge.rustunnel.com:4040",
        "--api",    "https://eu.edge.rustunnel.com:8443"
      ]
    }
  }
}
```

Once connected, you can ask the agent:

> "Expose my local server on port 3000 using my rustunnel token `<token>`."
> "Open an HTTP tunnel to port 8080 with subdomain `myapp`."
> "List all my active tunnels."

The agent will call `create_tunnel` and return a public URL like `https://abc123.eu.edge.rustunnel.com`.

***

### Self-hosted server

Replace the server address with your own instance:

```json theme={null}
{
  "mcpServers": {
    "rustunnel": {
      "command": "rustunnel-mcp",
      "args": [
        "--server", "your-server.com:4040",
        "--api",    "https://your-server.com:8443"
      ]
    }
  }
}
```

### Local development (self-signed cert)

```json theme={null}
{
  "mcpServers": {
    "rustunnel": {
      "command": "rustunnel-mcp",
      "args": [
        "--server",   "localhost:4040",
        "--api",      "http://localhost:4041",
        "--insecure"
      ]
    }
  }
}
```

### Cursor / VS Code / any MCP client

Most MCP clients use the same JSON format. Consult your client's documentation for the exact location of the config file.

### Custom / programmatic agents

Spawn `rustunnel-mcp` as a subprocess and communicate via stdin/stdout using newline-delimited JSON-RPC 2.0:

```python theme={null}
import subprocess, json

proc = subprocess.Popen(
    ["rustunnel-mcp", "--server", "localhost:4040"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
)

def call(method, params=None, id=1):
    msg = {"jsonrpc": "2.0", "id": id, "method": method}
    if params:
        msg["params"] = params
    proc.stdin.write(json.dumps(msg).encode() + b"\n")
    proc.stdin.flush()
    return json.loads(proc.stdout.readline())
```

***

## Available tools

### `create_tunnel`

Open a tunnel to a locally running service and get a public URL. Handles plain HTTP/TCP/UDP tunnels, peer-to-peer tunnels, and load-balanced pools.

| Parameter      | Type                                      | Required    | Description                                                                                                 |
| -------------- | ----------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------- |
| `token`        | string                                    | no¹         | API token. ¹Optional when `RUSTUNNEL_TOKEN` is set in the MCP config.                                       |
| `local_port`   | integer                                   | yes         | Local port the service is listening on                                                                      |
| `protocol`     | `"http"` \| `"tcp"` \| `"udp"` \| `"p2p"` | yes         | Tunnel type                                                                                                 |
| `subdomain`    | string                                    | no          | Custom subdomain for HTTP tunnels                                                                           |
| `region`       | string                                    | no          | Region ID (e.g. `"eu"`, `"us"`, `"ap"`). Omit to auto-select by latency. Use `list_regions` to see options. |
| `local_host`   | string                                    | no          | Local hostname to forward to (default `localhost`)                                                          |
| `secret`       | string                                    | p2p         | Shared P2P secret — publisher and subscriber must match                                                     |
| `peer_name`    | string                                    | p2p publish | Publish the local service under this name                                                                   |
| `peer_target`  | string                                    | p2p connect | Connect to a published P2P tunnel by this name                                                              |
| `group`        | string                                    | LB          | Load-balancing pool name (http/tcp only)                                                                    |
| `group_key`    | string                                    | LB          | Shared secret for the pool; members must agree                                                              |
| `health_check` | object                                    | no          | `{ type: "tcp"\|"http", path, interval_secs, timeout_secs, max_failed, expect_2xx, alert_webhook }`         |

**Returns:**

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

The MCP server spawns `rustunnel` as a background subprocess and polls the API until the tunnel appears (up to 15 seconds). Load-balanced tunnels are launched via a temporary `rustunnel start` config that is cleaned up automatically. The tunnel stays open until `close_tunnel` is called or the MCP server exits.

**Example agent prompts:**

> "Expose my local server on port 3000."
> "Open a P2P tunnel to port 3000 named `my-svc` with secret `hunter2`."
> "Load-balance ports 3000 and 3001 under subdomain `pool` with an HTTP health check on `/health`."

<Tip>
  Set `RUSTUNNEL_TOKEN` once in the MCP config (see the examples above) so you never have to pass `token` on a tool call. Get a key free at [rustunnel.com](https://rustunnel.com) → **Dashboard → API Keys** (or `rustunnel token create` on a self-hosted server).
</Tip>

***

### `list_tunnels`

List all currently active tunnels.

| Parameter | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| `token`   | string | no       | API token (optional if `RUSTUNNEL_TOKEN` is set) |

**Returns:** JSON array of tunnel objects from `GET /api/tunnels`.

***

### `close_tunnel`

Force-close a tunnel. The public URL stops working immediately.

| Parameter   | Type   | Required | Description                                        |
| ----------- | ------ | -------- | -------------------------------------------------- |
| `token`     | string | no       | API token (optional if `RUSTUNNEL_TOKEN` is set)   |
| `tunnel_id` | string | yes      | UUID returned by `create_tunnel` or `list_tunnels` |

***

### `get_connection_info`

Returns the CLI command (and, for load-balanced tunnels, a config file) without spawning anything. Use this when the MCP server cannot launch subprocesses (cloud sandboxes, containers) or when you want to run the CLI yourself. Accepts the **same arguments as `create_tunnel`** (`local_host`, `secret`/`peer_name`/`peer_target` for P2P, `group`/`group_key`/`health_check` for load balancing).

| Parameter    | Type                                      | Required | Description                                           |
| ------------ | ----------------------------------------- | -------- | ----------------------------------------------------- |
| `token`      | string                                    | no¹      | API token (¹optional if `RUSTUNNEL_TOKEN` is set)     |
| `local_port` | integer                                   | yes      | Local port to expose                                  |
| `protocol`   | `"http"` \| `"tcp"` \| `"udp"` \| `"p2p"` | yes      | Tunnel type                                           |
| `region`     | string                                    | no       | Region ID (e.g. `"eu"`, `"us"`). Omit to auto-select. |
| …            |                                           |          | plus the optional `create_tunnel` args above          |

**Returns:**

```json theme={null}
{
  "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"
}
```

***

### `list_regions`

List available tunnel server regions with their IDs, names, and locations. No authentication required.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| *(none)*  | —    | —        | —           |

**Returns:** JSON array of region objects:

```json theme={null}
[
  { "id": "eu", "name": "Europe", "location": "Helsinki, FI", "host": "eu.edge.rustunnel.com", "control_port": 4040, "active": true },
  { "id": "us", "name": "US West", "location": "Oregon, US", "host": "us.edge.rustunnel.com", "control_port": 4040, "active": true }
]
```

***

### `get_tunnel_history`

Retrieve the history of past tunnels.

| Parameter  | Type                                      | Required | Description                                      |
| ---------- | ----------------------------------------- | -------- | ------------------------------------------------ |
| `token`    | string                                    | no       | API token (optional if `RUSTUNNEL_TOKEN` is set) |
| `protocol` | `"http"` \| `"tcp"` \| `"udp"` \| `"p2p"` | no       | Filter by protocol                               |
| `limit`    | integer                                   | no       | Max entries to return (default: 25)              |

***

## Agent workflow examples

### Local agent exposing a dev server

```text theme={null}
1. Agent has a pre-existing API token (obtained from the dashboard or via
   the CLI: rustunnel token create --name agent-session)

2. Agent calls create_tunnel(token="...", local_port=3000, protocol="http")
   → MCP server spawns: rustunnel http 3000 --server ... --token ...
   → Returns: { public_url: "https://xyz.eu.edge.rustunnel.com", tunnel_id: "..." }

3. Agent returns the public URL to the user.

4. Later: Agent calls close_tunnel(token="...", tunnel_id="...")
   → MCP server calls DELETE /api/tunnels/:id and kills the subprocess
```

### Cloud agent (no subprocess access)

```text theme={null}
1. Agent calls get_connection_info(token="...", local_port=8000, protocol="http")
   → Returns: { cli_command: "rustunnel http 8000 --server ... --token ..." }

2. Agent outputs the command. User runs it in their local environment.

3. Agent calls list_tunnels(token="...") to confirm the tunnel is active
   and retrieve the public URL.
```

***

## Token management

### Hosted service

Sign up at [rustunnel.com](https://rustunnel.com), then create an API key from the dashboard under **Settings → API Keys**.

### Self-hosted server

Create tokens via the dashboard UI, the CLI, or the REST API:

```bash theme={null}
# CLI
rustunnel token create --name agent-session

# 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"}'
```

<Warning>Store the raw token value securely — it is shown only once at creation time.</Warning>

***

## OpenAPI spec

The server exposes a machine-readable API description at:

```text theme={null}
GET /api/openapi.json
```

No authentication required. Useful for agent discovery and client generation.

```bash theme={null}
curl http://localhost:4041/api/openapi.json | jq .info
```

***

## Security notes

* The `rustunnel` binary must be installed and in `PATH` on the machine running `rustunnel-mcp` for `create_tunnel` to work.
* Tokens passed to tools are sent to the rustunnel server over HTTPS (or HTTP in local dev). Use HTTPS in production.
* Child processes spawned by `create_tunnel` are killed when the MCP server exits (stdin closes). They are not persisted across MCP server restarts.
* Use `--insecure` only in local development with self-signed certificates.

***

## Related pages

<CardGroup>
  <Card title="Agent integration" icon="bot" href="/docs/guides/agent-integration">
    Copy-paste MCP config for Claude Code, Claude Desktop, Codex, Cursor, Windsurf, and Cline.
  </Card>

  <Card title="Claude Code plugin" icon="plug" href="/docs/guides/claude-plugin">
    One-command install that wraps this MCP server for Claude Code.
  </Card>

  <Card title="Self-hosting" icon="server" href="/docs/guides/self-hosting">
    Run your own rustunnel server for the MCP server to connect to.
  </Card>

  <Card title="Load balancing" icon="route" href="/docs/reference/load-balancing">
    Pools, group keys, and health checks used by load-balanced tunnels.
  </Card>

  <Card title="AI tools hub" icon="bot" href="https://rustunnel.com/ai-tools/mcp">
    Quick-start version of this page with install one-liners and an agent-ready prompt.
  </Card>

  <Card title="Agent manual" icon="file-lines" href="https://rustunnel.com/agents.md">
    Copy-paste recipes and an FAQ for AI agents, served as plain markdown.
  </Card>
</CardGroup>


# Request Inspector — browse and replay tunnel traffic on localhost:4040
Source: https://rustunnel.com/docs/guides/request-inspector

Every rustunnel session starts a local web inspector on loopback. Browse HTTP requests, inspect headers and bodies, and one-click Replay payloads against your local service — the ngrok :4040 equivalent, built into the open-source CLI.

Every `rustunnel` tunnel session starts a small **web request inspector** on loopback. Open it while a tunnel is live to browse the traffic that flowed through, inspect headers and bodies, and **Replay** any request against your local service — without the original caller doing anything.

This is the ngrok `:4040` equivalent, built into the open-source CLI (shipping in **0.8.3**).

## Open the inspector

Start any tunnel as usual:

```bash theme={null}
rustunnel http 3000
```

The inspector URL is printed at startup and shown in the [terminal UI](/docs/guides/client-guide#terminal-ui) header:

```text theme={null}
Inspect http://127.0.0.1:4040
```

Open that URL in a browser on the same machine.

<Frame>
  <img alt="rustunnel request inspector detail view with Replay button" />
</Frame>

## What you can do

* **Request list** — live-updating table with method, path, status, and duration. Filter by method, path, or status.
* **Detail view**
  * **Summary** — request and response bodies
  * **Headers** — full request and response headers
  * **Raw** — reconstructed HTTP messages
* **Replay** — re-issue any captured request against your local service. Ideal for webhook development: trigger once from Stripe/GitHub/etc., then iterate against the same payload. Replayed rows are marked `replay` in the list (and `↻` in the terminal UI).

<Frame>
  <img alt="rustunnel request inspector list view" />
</Frame>

## Scope and limits

* Captures **HTTP tunnels only**. TCP and UDP tunnels are raw byte streams; they contribute connection and traffic counters in the terminal UI but no request entries here.
* Keeps the **last 500 requests in memory**, per process. Nothing is written to disk and nothing survives a restart.
* Bodies are captured up to **64 KB each**; larger ones are marked truncated (the reported size is still exact). A truncated request body cannot be replayed byte-for-byte.
* WebSocket and other upgraded connections are recorded as their handshake (`101`); frames afterwards are not parsed.

## Configuration

| Flag                    | Effect                                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--inspect-port <port>` | Bind a specific port (default `4040`). If it is taken, the next free port is used and the real URL is displayed. |
| `--no-inspect`          | Disable the inspector entirely.                                                                                  |

```bash theme={null}
# Prefer port 9090 for the inspector
rustunnel http 3000 --inspect-port 9090

# Disable capture on a shared machine
rustunnel http 3000 --no-inspect
```

Because the port can shift when the preferred one is taken, always read the **actual** URL rather than assuming `4040`:

* Terminal UI header (`Inspect http://127.0.0.1:…`)
* Line under the startup box in line mode
* `inspector_ready` NDJSON event in `--json` mode

```json theme={null}
{"event":"inspector_ready","url":"http://127.0.0.1:4040"}
{"event":"tunnel_ready","protocol":"http","public_url":"https://myapp.eu.edge.rustunnel.com","local_port":3000,"local_host":"localhost"}
```

## Security

The inspector binds **`127.0.0.1` only** and has **no authentication**. Treat it as local-only — captured payloads may contain credentials, tokens, and personal data. Use `--no-inspect` on shared or multi-user machines.

## Related

<CardGroup>
  <Card title="Client Guide" icon="terminal" href="/docs/guides/client-guide">
    Full CLI reference — terminal UI, flags, config, and reconnection.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Expose localhost in three steps.
  </Card>

  <Card title="Webhook testing use case" icon="webhook" href="https://rustunnel.com/use-cases/webhook-testing">
    Marketing landing for local webhook testing workflows.
  </Card>

  <Card title="MCP Server" icon="robot" href="/docs/guides/mcp-server">
    Drive tunnels from AI agents in plain language.
  </Card>
</CardGroup>


# Self-Host the rustunnel Tunnel Server on Ubuntu (systemd, TLS, PostgreSQL)
Source: https://rustunnel.com/docs/guides/self-hosting

Self-host the open-source rustunnel server on a Linux VPS with systemd, Let's Encrypt TLS, and PostgreSQL. Production-ready walkthrough — drop-in for ngrok or frp on any cloud provider including Hetzner, DigitalOcean, and Linode.

This guide walks through how to **self-host the rustunnel tunnel server** in production. rustunnel is open-source under AGPL, so you can run the same server we run on the managed cloud — on any VPS with a public IP and a wildcard DNS record. The example commands use **Ubuntu 22.04**, systemd, Let's Encrypt TLS via Certbot, and PostgreSQL, but the same recipe works on any major cloud provider including Hetzner, DigitalOcean, Linode, and AWS Lightsail. For a Docker-based deployment, see the [Docker Deployment](/docs/guides/docker-deployment) guide instead.

## Requirements

### To build

| Requirement    | Version | Notes                                   |
| -------------- | ------- | --------------------------------------- |
| Rust toolchain | 1.76+   | Install via [rustup](https://rustup.rs) |
| `pkg-config`   | any     | Required by `reqwest` (TLS)             |
| `libssl-dev`   | any     | `apt install libssl-dev`                |
| Node.js + npm  | 18+     | Only needed to rebuild the dashboard UI |

### To run

| Requirement           | Notes                                                                        |
| --------------------- | ---------------------------------------------------------------------------- |
| Linux (Ubuntu 22.04+) | systemd service included                                                     |
| Public IP + DNS       | Wildcard DNS `*.tunnel.yourdomain.com → server IP` required for HTTP tunnels |
| TLS certificate       | PEM format — Let's Encrypt recommended                                       |
| PostgreSQL            | Stores API tokens and tunnel audit log                                       |

***

## Step 1 — Install dependencies

```bash theme={null}
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 theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```

***

## Step 2 — Build release binaries

```bash theme={null}
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`

***

## Step 3 — Create system user and directories

```bash theme={null}
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
```

***

## Step 4 — Install the server binary

```bash theme={null}
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 shortcut (runs build + install + systemd setup):

```bash theme={null}
sudo make deploy
```

***

## Step 5 — Set up PostgreSQL

rustunnel requires PostgreSQL for shared state (tokens, tunnel history, audit log).

```bash theme={null}
apt install -y postgresql postgresql-contrib

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

Create a dedicated database and user:

```bash theme={null}
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 Databases, Supabase) skip the `apt install` step and just note down your connection URL for the config in the next step.</Tip>

Schema migrations run automatically when the server starts — no manual SQL needed.

***

## Step 6 — Create the server config file

Create `/etc/rustunnel/server.toml`. Generate a strong admin token first:

```bash theme={null}
openssl rand -hex 32
```

```toml theme={null}
# /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
# Failed authentication attempts allowed per source IP per minute before
# further attempts are rejected. Set to 0 to disable the throttle.
max_failed_auth_per_minute = 10

# ── 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.
# The directory must be writable by the rustunnel user.
captured_path = "/var/lib/rustunnel/captured.db"

# ── Logging ──────────────────────────────────────────────────────────────────
[logging]
level  = "info"
format = "json"

# Optional: append-only audit log (JSON-lines).
# Records auth attempts, tunnel registrations, token creation/deletion.
# Omit or comment out to disable.
audit_log_path = "/var/lib/rustunnel/audit.log"

# ── Limits ───────────────────────────────────────────────────────────────────
[limits]
max_tunnels_per_session    = 10
max_connections_per_tunnel = 100
rate_limit_rps             = 100
ip_rate_limit_rps          = 100
request_body_max_bytes     = 10485760   # 10 MB

# Inclusive port range reserved for TCP tunnels.
tcp_port_range = [20000, 20099]
```

Secure the file:

```bash theme={null}
chown root:rustunnel /etc/rustunnel/server.toml
chmod 640 /etc/rustunnel/server.toml
```

***

## Step 7 — TLS certificates (Let's Encrypt + Cloudflare)

Both the bare domain and the wildcard are required. The wildcard (`*.edge.rustunnel.com`) is what makes HTTP subdomain tunnels work.

Create the Cloudflare credentials file:

```bash theme={null}
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 the certificate:

```bash theme={null}
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 PEM files to:

```text theme={null}
/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem
/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem
```

Certbot installs a systemd timer for automatic renewal. rustunnel reads TLS certificates
from disk at startup, so it must be restarted after each renewal. Add a deploy hook to
do this automatically:

```bash theme={null}
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 theme={null}
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
```

***

## Step 8 — Set up the systemd service

```bash theme={null}
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
```

***

## Step 9 — Open firewall ports

```bash theme={null}
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"
ufw allow 20000:20099/tcp comment "rustunnel TCP tunnels"
```

<Note>Port 9090 only needs to be open if you have an external Prometheus scraper. If Prometheus runs on the same host it reaches the metrics endpoint over the loopback network.</Note>

***

## Step 10 — Verify the server is running

```bash theme={null}
# Health check (dashboard is plain HTTP on dashboard_port)
curl http://localhost:8443/api/status

# Check bound ports
ss -tlnp | grep rustunnel-serve

# Startup logs
journalctl -u rustunnel.service --no-pager | tail -30

# Prometheus metrics
curl -s http://localhost:9090/metrics
```

<Note>Port 4040 is the control-plane WebSocket — clients connect here. Hitting it with plain HTTP returns `HTTP/0.9`, which is expected. The dashboard REST API is on `dashboard_port` (8443 in the config above).</Note>

***

## Connecting a client

```bash theme={null}
rustunnel http 3000 \
  --server edge.rustunnel.com:4040 \
  --token YOUR_ADMIN_TOKEN
```

***

## Updating the server

Pull the latest code, rebuild, install, and restart in one command:

```bash theme={null}
cd ~/rustunnel && sudo make update-server
```

This runs: `git pull` → `cargo build --release` → `install` → `systemctl restart` → `systemctl status`.

***

## Port reference

| Port          | Protocol | Purpose                                                |
| ------------- | -------- | ------------------------------------------------------ |
| `80`          | TCP      | HTTP edge — redirects to HTTPS; 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`)   |

***

## Config file reference

| Key                                 | Type        | Default                          | Description                                                                                                                                          |
| ----------------------------------- | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.domain`                     | string      | —                                | Base domain for tunnel URLs                                                                                                                          |
| `server.http_port`                  | u16         | —                                | HTTP edge port                                                                                                                                       |
| `server.https_port`                 | u16         | —                                | HTTPS edge port                                                                                                                                      |
| `server.control_port`               | u16         | —                                | WebSocket control-plane port                                                                                                                         |
| `server.dashboard_port`             | u16         | `4040`                           | Dashboard REST API port                                                                                                                              |
| `server.dashboard_origin`           | string      | `""`                             | Allowed CORS origin for the dashboard UI                                                                                                             |
| `tls.cert_path`                     | string      | —                                | Path to TLS certificate (PEM)                                                                                                                        |
| `tls.key_path`                      | string      | —                                | 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.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      | —                                | Master auth token                                                                                                                                    |
| `auth.require_auth`                 | bool        | —                                | Reject unauthenticated clients                                                                                                                       |
| `auth.max_failed_auth_per_minute`   | u32         | `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      | —                                | PostgreSQL connection URL (required)                                                                                                                 |
| `database.captured_path`            | string      | `/var/lib/rustunnel/captured.db` | Per-region SQLite file for captured HTTP request bodies                                                                                              |
| `logging.level`                     | string      | —                                | `trace` / `debug` / `info` / `warn` / `error`                                                                                                        |
| `logging.format`                    | string      | —                                | `json` or `pretty`                                                                                                                                   |
| `logging.audit_log_path`            | string      | `null`                           | Audit log path (JSON-lines); omit to disable                                                                                                         |
| `limits.max_tunnels_per_session`    | usize       | —                                | Max tunnels per connected client                                                                                                                     |
| `limits.max_connections_per_tunnel` | usize       | —                                | Max concurrent connections per tunnel                                                                                                                |
| `limits.rate_limit_rps`             | u32         | —                                | 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       | —                                | Max proxied request body size (bytes)                                                                                                                |
| `limits.tcp_port_range`             | \[u16, u16] | —                                | Inclusive `[low, high]` TCP tunnel port range                                                                                                        |
| `region.id`                         | string      | `"default"`                      | Region identifier (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`:

```text theme={null}
rustunnel_active_sessions      # gauge: connected clients
rustunnel_active_tunnels_http  # gauge: active HTTP tunnels
rustunnel_active_tunnels_tcp   # gauge: active TCP tunnels
```

Start the full monitoring stack (Prometheus + Grafana):

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

<Warning>The default Grafana password is `changeme`. Set `GRAFANA_PASSWORD` before starting the stack in production.</Warning>

```bash theme={null}
export GRAFANA_PASSWORD=your-strong-password
make docker-run-monitoring
```

***

## Next steps

<CardGroup>
  <Card title="Client Guide" icon="terminal" href="/docs/guides/client-guide">
    Configure the rustunnel CLI to connect to your self-hosted server.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/docs/guides/architecture">
    Understand the control plane, data plane, and yamux multiplexing under the hood.
  </Card>

  <Card title="Load Balancing & Health Checks" icon="scale-balanced" href="/docs/reference/load-balancing">
    Run multiple backends behind one subdomain with automatic failover.
  </Card>

  <Card title="MCP Server" icon="robot" href="/docs/guides/mcp-server">
    Let AI agents manage tunnels on your self-hosted server via MCP.
  </Card>
</CardGroup>


# rustunnel docs — open-source, self-hosted tunnel server
Source: https://rustunnel.com/docs/index

Documentation for rustunnel — the open-source, self-hosted secure tunnel server written in Rust that exposes localhost, webhooks, and TCP/UDP services to the internet. Self-host the tunnel server or use the managed cloud — same client binary, same docs. A self-hostable ngrok alternative.

**rustunnel** is an open-source secure tunnel server written in Rust that exposes localhost over encrypted WebSocket connections. [Self-host it on any VPS](/docs/guides/self-hosting) or use our [managed cloud](https://rustunnel.com) — an [ngrok alternative](/docs/quickstart) with automatic Let's Encrypt TLS, HTTP / TCP / UDP / P2P proxying, a live dashboard, Prometheus metrics, and audit logging.

If you're new here, the fastest way in is the [Quickstart](/docs/quickstart) — install the client and open your first tunnel in three steps. If you want to know how it fits together, jump to the [Architecture](/docs/guides/architecture) page; to drive tunnels from an AI agent, start with the [agent integration guide](/docs/guides/agent-integration).

## Setting up

Get a tunnel running in minutes.

<Card title="Start here" icon="rocket" href="/docs/quickstart">
  Follow the quickstart guide to install the client and open your first tunnel.
</Card>

## Explore the docs

<Columns>
  <Card title="Client Guide" icon="terminal" href="/docs/guides/client-guide">
    All commands, flags, config file options, region selection, and troubleshooting.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/docs/guides/docker-deployment">
    Run the server locally with a self-signed cert or deploy to a VPS with Let's Encrypt.
  </Card>

  <Card title="Self-Hosting" icon="server" href="/docs/guides/self-hosting">
    Production deployment on Ubuntu with systemd, TLS, PostgreSQL, and firewall rules.
  </Card>

  <Card title="MCP Server" icon="robot" href="/docs/guides/mcp-server">
    Let AI agents (Claude, GPT-4o, Gemini) open and manage tunnels automatically.
  </Card>
</Columns>

## Go deeper

<Columns>
  <Card title="Architecture" icon="sitemap" href="/docs/guides/architecture">
    Internals: control protocol, yamux data plane, concurrency model, and crate structure.
  </Card>

  <Card title="Load Balancing & Health Checks" icon="scale-balanced" href="/docs/reference/load-balancing">
    Run multiple backends behind one subdomain or TCP port. Random dispatch across healthy members with automatic failover.
  </Card>

  <Card title="P2P Tunnels" icon="arrows-left-right" href="/docs/reference/p2p-tunnels">
    Direct peer-to-peer connections with NAT hole punching over QUIC, with automatic relay fallback.
  </Card>

  <Card title="UDP Tunnels" icon="bolt" href="/docs/reference/udp-tunnels">
    Forward UDP datagrams (game servers, DNS, QUIC, VoIP) to a public port on the rustunnel server.
  </Card>
</Columns>

## Use rustunnel with AI agents

<Columns>
  <Card title="Claude Code Plugin" icon="robot" href="/docs/guides/claude-plugin">
    Install the rustunnel Claude Code plugin in one command. The agent gets six tunnel-management tools and your token is stored securely.
  </Card>

  <Card title="MCP Server (Cursor, Windsurf, any agent)" icon="plug" href="/docs/guides/mcp-server">
    Wire the rustunnel MCP server into Cursor, Windsurf, Claude Desktop, OpenClaw, or any other MCP-compatible client to expose localhost on demand.
  </Card>
</Columns>


# rustunnel Quickstart — expose localhost in three steps
Source: https://rustunnel.com/docs/quickstart

Install the rustunnel client, sign in with an API token, and expose your first local service over HTTPS in three steps. The fastest way to put localhost on the public internet with an open-source, self-hostable ngrok alternative.

This quickstart takes you from nothing to a live public URL for your local service in three steps: install the rustunnel client, get an auth token, and open a tunnel. The same steps work against the managed cloud at [rustunnel.com](https://rustunnel.com) or your own [self-hosted server](/docs/guides/self-hosting).

## Step 1 — Install the client

<AccordionGroup>
  <Accordion title="macOS and Linux (Homebrew)" icon="apple">
    ```bash theme={null}
    brew tap joaoh82/rustunnel
    brew install rustunnel
    ```

    This installs both `rustunnel` (the CLI client) and `rustunnel-mcp` (the MCP server for AI agent integration). No Rust toolchain required.
  </Accordion>

  <Accordion title="Pre-built binary" icon="download">
    Download the archive for your platform from the [latest GitHub Release](https://github.com/joaoh82/rustunnel/releases/latest), extract it, and move the binary onto your `$PATH`.

    | 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)  | `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`       |
  </Accordion>

  <Accordion title="Build from source" icon="code">
    Requires [Rust](https://rustup.rs) 1.76 or later.

    ```bash theme={null}
    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
    ```
  </Accordion>
</AccordionGroup>

Verify the installation:

```bash theme={null}
rustunnel --version
```

***

## Step 2 — Get an auth token

Access to the hosted service requires an auth token. Create a free account and generate one yourself.

<Steps>
  <Step title="Create a free account">
    Sign up at [rustunnel.com](https://rustunnel.com).
  </Step>

  <Step title="Generate a token">
    Go to **Dashboard → API Keys → Create token** and copy the token value.
  </Step>

  <Step title="Run the setup wizard">
    ```bash theme={null}
    rustunnel setup
    ```

    The wizard prompts for your region and token, then writes `~/.rustunnel/config.yml` with the correct server address.

    ```text theme={null}
    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
    ```

    Pick a specific region (`eu`, `us`, `ap`) to skip probing, or `self-hosted` if you run your own server.
  </Step>
</Steps>

<Note>If you are self-hosting, skip token requests entirely — use the `admin_token` you set in your `server.toml`. See the [Self-Hosting guide](/docs/guides/self-hosting).</Note>

***

## Step 3 — Open your first tunnel

```bash theme={null}
# Expose a local HTTP service on port 3000
rustunnel http 3000

# Connect to a specific region
rustunnel http 3000 --region eu

# Request a custom subdomain
rustunnel http 3000 --subdomain myapp

# Expose a raw TCP service (e.g. PostgreSQL)
rustunnel tcp 5432

# Expose a UDP service (e.g. game server)
rustunnel udp 27015

# P2P tunnel — connect two clients directly
rustunnel p2p 27015 --name my-game --secret "shared-secret"
```

On a real terminal the client opens a **live dashboard** (session status, region latency, traffic counters, scrolling request log) and starts a **local request inspector**:

```text theme={null}
Inspect http://127.0.0.1:4040
```

Open that URL to browse headers/bodies and one-click **Replay** any request against your local service — handy for webhook iteration. Details: [Terminal UI](/docs/guides/client-guide#terminal-ui) and [Request Inspector](/docs/guides/request-inspector).

In line mode (`--no-tui`, piped stdout, or CI) you still get the public URL and inspector line:

```text theme={null}
  Selecting nearest region… eu 12ms · us 143ms · ap 311ms → eu (Helsinki, FI) 12ms
╭────────────────────────────────────────────────────────────╮
│                         rustunnel                          │
├────────────────────────────────────────────────────────────┤
│   HTTP → localhost:3000                                    │
│   https://abc123.eu.edge.rustunnel.com                     │
╰────────────────────────────────────────────────────────────╯
  ✓ Tunnels active. Press Ctrl-C to quit.
  Inspect http://127.0.0.1:4040
```

Press `q` / `Esc` / `Ctrl-C` to close the tunnel.

***

## Available regions

| Region | Location      | Server                       |
| ------ | ------------- | ---------------------------- |
| `eu`   | Helsinki, FI  | `eu.edge.rustunnel.com:4040` |
| `us`   | Hillsboro, OR | `us.edge.rustunnel.com:4040` |
| `ap`   | Singapore     | `ap.edge.rustunnel.com:4040` |

The client auto-selects the nearest region by default when `region: auto` is set in your config.

***

## Next steps

<CardGroup>
  <Card title="Client Guide" icon="terminal" href="/docs/guides/client-guide">
    All commands, flags, live terminal UI, config options, and error reference.
  </Card>

  <Card title="Request Inspector" icon="magnifying-glass" href="/docs/guides/request-inspector">
    Browse and replay HTTP traffic on localhost:4040 while a tunnel is live.
  </Card>

  <Card title="Self-Hosting" icon="server" href="/docs/guides/self-hosting">
    Run your own rustunnel server on a VPS with systemd and Let's Encrypt.
  </Card>

  <Card title="MCP Server" icon="robot" href="/docs/guides/mcp-server">
    Let AI agents manage tunnels on your behalf via the Model Context Protocol.
  </Card>
</CardGroup>


# Tunnel Load Balancing with Multiple Backends and Health Checks
Source: https://rustunnel.com/docs/reference/load-balancing

Run multiple backends behind one rustunnel subdomain or TCP port. Inbound connections are dispatched at random across healthy members, with TCP and HTTP health probes that automatically remove sick backends from the rotation — a managed-cloud equivalent of FRP's loadBalancer.group config.

This page documents **rustunnel's group-based load balancing** — how to run multiple backends behind a single tunnel with **built-in TCP and HTTP health checks**. Multiple clients can register against the same subdomain (HTTP) or share a TCP port pool, and inbound connections are dispatched at random across healthy members of the group. Optional client-side health probes automatically remove sick backends from the rotation, so the edge never wastes a request on a degraded upstream.

The model is intentionally close to FRP's [`loadBalancer.group` / `healthCheck`](https://github.com/fatedier/frp#load-balancing) config — same shape, slightly different wire format — so anyone migrating from `frp` will recognise the configuration surface.

## Concepts

* **Group** — a logical pool of tunnel members sharing the same subdomain (HTTP) or TCP port. Identified by a user-supplied `group` name plus a shared `group_key`. The server stores only the SHA-256 hash of the key and uses it to authorise joins; the raw key never leaves the client.
* **Member** — one tunnel inside a group. Running two clients with the same `(group, group_key)` produces a 2-member pool.
* **Health bit** — every member has a `healthy` flag. Dispatch routes around members whose flag is `false`. Without a health check configured, members are permanently healthy (the server trusts the client's presence).
* **Dispatch** — for each new public connection, the server picks one healthy member uniformly at random. There's no weighting and no sticky sessions today.

```text theme={null}
                  +-> client A -> backend on :3000
public ─-->  ── group "web"
                  +-> client B -> backend on :3001
```

***

## Configuration

### Server (`server.toml`)

The kill switch. When `false` (the default), the server accepts the new fields on the wire but ignores them — every registration is a solo tunnel. When `true`, members sharing `(subdomain, group_key_hash)` (HTTP) or `(group_name, group_key_hash)` (TCP) form a real pool.

```toml theme={null}
[load_balancing]
enabled = true
```

<Note>
  The kill switch is per-region for self-hosted multi-region deployments. Flip it on regions one at a time during a rollout — `false` is the safe default that preserves single-tunnel-per-key behaviour.
</Note>

### Client (`~/.rustunnel/config.yml`)

Add `group`, `group_key`, and optionally `health_check` to a tunnel definition:

```yaml theme={null}
server: tunnel.example.com:4040
auth_token: "your-token"

tunnels:
  a:
    proto: http
    local_port: 3000
    subdomain: pool
    group: web
    group_key: shared-secret-for-this-pool
    health_check:
      type: tcp
      interval_secs: 10
      timeout_secs: 3
      max_failed: 3
```

| Field                        | Required              | Default | Meaning                                                                                                                                           |
| ---------------------------- | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group`                      | yes (for LB)          | —       | Display name of the pool. The first joiner sets `TunnelGroup.name`; later joiners are accepted regardless of what they pass.                      |
| `group_key`                  | yes (for LB)          | —       | Shared secret. SHA-256-hashed before transmission. Members of one pool MUST agree on this value; the server rejects a join with a mismatched key. |
| `health_check.type`          | no                    | —       | `tcp` (open a connection) or `http` (issue a `GET`). Omit to disable probing.                                                                     |
| `health_check.path`          | yes when `type: http` | —       | Path to GET against the local service.                                                                                                            |
| `health_check.interval_secs` | no                    | `10`    | Probe period.                                                                                                                                     |
| `health_check.timeout_secs`  | no                    | `3`     | Per-probe deadline.                                                                                                                               |
| `health_check.max_failed`    | no                    | `3`     | Consecutive failures before reporting `TunnelUnhealthy`.                                                                                          |
| `health_check.expect_2xx`    | no                    | `true`  | When `false`, any HTTP response counts as healthy.                                                                                                |
| `health_check.alert_webhook` | no                    | —       | Per-tenant URL the server POSTs to when *this group* transitions to 0 healthy members. See [Webhook alerts](#webhook-alerts) below.               |

***

## Behaviour rules

<AccordionGroup>
  <Accordion title="HTTP groups">
    Members must declare the same protocol (`http` vs `https`). A mismatch is rejected with a clear error. The subdomain is the routing key — every member of a group shares one subdomain.
  </Accordion>

  <Accordion title="TCP groups">
    The first member of a `(group, group_key)` allocates a port from the configured `tcp_port_range`. Subsequent members **reuse** that port; the server returns the same `assigned_port` to all joiners. Members never see a `Registered` listener event after the first — the listener is already bound.
  </Accordion>

  <Accordion title="Solo collisions">
    Registering a solo (no-group) tunnel against an existing group's subdomain is rejected with `subdomain '...' is already in use`. Registering a grouped tunnel against an existing solo tunnel is rejected with `group key does not match`. A subdomain is owned by exactly one identity at a time.
  </Accordion>

  <Accordion title="Last-leave semantics">
    The group entry is removed when its last member disconnects. The TCP port (if any) is returned to the pool. New registrations after that point start a fresh group with a fresh port.
  </Accordion>

  <Accordion title="Race safety">
    The create / join / remove paths are serialised atomically via the routing-table entry API. Two concurrent first registrations produce one group, not two.
  </Accordion>
</AccordionGroup>

***

## Health checks

Probes run **on the client** against `local_addr`. The server never opens a connection to the upstream itself — it just trusts the client's `TunnelHealthy` / `TunnelUnhealthy` reports.

* **TCP probe**: opens a TCP connection. Success = connect within `timeout_secs`.
* **HTTP probe**: sends `GET <path> HTTP/1.0` and reads the status line. Success = response within `timeout_secs` and (when `expect_2xx`) status in `[200, 300)`.

Probe state is reported only on **edges**:

<Steps>
  <Step title="First probe success">
    Emits `TunnelHealthy` — lifts the initial `healthy=false` state for members that opted into probing.
  </Step>

  <Step title={"`max_failed` consecutive failures"}>
    Emits `TunnelUnhealthy`. The server flips the `healthy` bit to `false` and excludes the member from dispatch.
  </Step>

  <Step title="First success after a failure streak">
    Emits `TunnelHealthy`. The server resets the consecutive-failure counter and re-includes the member.
  </Step>
</Steps>

A member with no `health_check` is permanently healthy. A member *with* a spec starts unhealthy and only joins dispatch after the first successful probe.

***

## Webhook alerts

When a load-balancing group transitions to **0 healthy members**, public traffic to that subdomain or port starts returning 502. The server can POST a JSON alert to one or more URLs at the moment of that transition so an operator or tenant can react.

There are **two distinct destinations**, each addressing a different audience:

### Operator URL — `[load_balancing] alert_webhook_url` in `server.toml`

Set on the **edge**. Fires for every group on that edge that goes 0/N, regardless of which tenant owns the group. Useful for self-hosted deployments and for ops awareness on a managed multi-tenant edge.

```toml theme={null}
[load_balancing]
enabled = true
alert_webhook_url = "https://hooks.slack.com/services/operator-channel/..."
```

### Per-tenant URL — `health_check.alert_webhook` in the client config

Set on the **client**. Fires only when the group containing this tunnel goes 0/N. Each tenant points it at *their* Slack / PagerDuty / email gateway. The URL is sent on the wire as part of `HealthCheckSpec` and stored on the affected `GroupMember`; only the server holds it (the URL is never returned by `/api/groups` — dashboards see a presence-only flag).

```yaml theme={null}
tunnels:
  a:
    proto: http
    local_port: 3000
    subdomain: pool
    group: web
    group_key: shared-secret-for-this-pool
    health_check:
      type: tcp
      alert_webhook: "https://hooks.slack.com/services/my-team/..."
```

Both destinations can be configured independently. Both fire on the same 0/N transition. The server collects unique URLs from the affected group's members (so two members of one tenant pointing at the same URL receive a **single** POST per transition, not two), then fans out to each unique URL plus the operator URL.

### Payload

Same JSON body sent to every destination:

```json theme={null}
{
  "event": "group_zero_healthy",
  "region_id": "eu",
  "protocol": "http",
  "label": "pool",
  "group_name": "web",
  "key_hash_short": "deadbeef",
  "member_count": 2,
  "at": "2026-05-06T13:24:55+00:00"
}
```

`key_hash_short` is the first 8 hex chars of the group's SHA-256 key hash — stable across reconnects, useful for correlating alerts when a single team runs multiple pools with the same `group_name`.

### Debounce

The server tracks a per-group `zero_healthy_alerted` flag. Once an alert fires, **subsequent `TunnelUnhealthy` frames against the same already-down group do not re-fire**. The flag resets the moment any member becomes healthy again — the next 0/N transition then fires fresh.

In practice: if your pool flaps badly (down → up → down → up), each *downward edge* generates one alert per destination. Steady-state "everyone is still down" generates none.

### Delivery

<Note>
  Best-effort. The server uses a 5-second per-request timeout, no retry, no queue. If your webhook receiver is down at the moment of the transition, the alert is lost. For high-stakes paging, point the URL at something durable — a queueing alertmanager, or a service like Pushover with retry — rather than relying on the rustunnel server for delivery guarantees.
</Note>

The fire happens in a detached `tokio::spawn`, so a slow webhook receiver never blocks the server's frame-handling hot path.

***

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

<Steps>
  <Step title="Build the client from source">
    ```bash theme={null}
    git clone https://github.com/joaoh82/rustunnel
    cd rustunnel
    cargo build --release -p rustunnel-client
    ```
  </Step>

  <Step title="Drop a config that opts into a group">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Start backend A on :3000">
    ```bash theme={null}
    python3 -m http.server 3000
    ```
  </Step>

  <Step title="Start client A pointing at backend A">
    ```bash theme={null}
    ./target/release/rustunnel start --config /tmp/lb-test.yml
    ```
  </Step>

  <Step title="Start backend B on :3001">
    In a separate terminal:

    ```bash theme={null}
    python3 -m http.server 3001
    ```
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Hammer the public URL">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify via the metrics endpoint">
    ```bash theme={null}
    ssh root@tunnel.example.com 'curl -sf http://127.0.0.1:9090/metrics' \
      | grep '^rustunnel_group_'
    ```

    Expect output like:

    ```text theme={null}
    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
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Observability

When `[load_balancing] enabled = true`, the Prometheus exporter on `:9090` emits three additional series:

| Metric                                  | Type    | Labels                       | What it measures                                                                                                                     |
| --------------------------------------- | ------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `rustunnel_group_members`               | gauge   | `group`, `region`, `healthy` | Count of registered members partitioned by their health bit.                                                                         |
| `rustunnel_group_dispatches_total`      | counter | `group`, `region`            | Total dispatched connections, summed across the group's members. Per-group rather than per-member to keep label cardinality bounded. |
| `rustunnel_group_health_failures_total` | counter | `group`, `region`, `kind`    | Total `TunnelUnhealthy` frames received across the group's members. `kind` is `tcp` / `http` / `none` based on the probe type.       |

The pre-existing `rustunnel_active_tunnels_*` and `rustunnel_requests_total` gauges/counters keep counting **members** (not groups) so historical dashboards stay accurate.

### Per-tunnel timeline + live event stream

Two REST surfaces let dashboards reconstruct *recent* health behaviour without polling all of `/api/tunnels`:

* `GET /api/tunnels/:id/health-events` — last 50 health-state transitions for that tunnel (`{ at, healthy, reason }[]`, oldest first). Records edges only — steady-state probe reports are not stored. Use this to render a per-tunnel timeline panel.
* `GET /api/groups/:protocol/:label/events` — Server-Sent Events stream emitting one `group_event` per member health-bit transition affecting the named group. 30s keep-alive ping. Use this for live dashboards that want push instead of polling. A `lagged` SSE event means the consumer fell behind — resync via `/api/groups`.

Both endpoints are gated by the same auth as `/api/tunnels` (admin token or DB token), and they apply the same per-tenant scope: a user-scoped DB token sees only groups containing at least one of its own members; aggregate counters reflect just the visible members; groups the caller can't see return `404` rather than `403`. Admin tokens see everything.

***

## Limitations & non-goals

<Info>
  rustunnel's load balancing is intentionally minimal. If you need any of the features below, layer them at the application or DNS level.
</Info>

* **No weighted dispatch** — random uniform only.
* **No sticky sessions** — every new connection is dispatched independently. Long-lived WebSocket connections that need affinity must handle reconnects at the application layer.
* **No active session draining on member removal** — in-flight connections finish naturally; new connections route elsewhere.
* **No UDP groups** — UDP is connectionless; there's no obvious unit to dispatch.
* **No P2P groups** — P2P publishers are 1-to-many by design.
* **No cross-region pools** — members must be on the same edge server. Layer DNS-based routing on top for global LB.
* **No `groupKey` rotation** — once a group exists, rotating its key requires dropping all members.

***

## See also

<CardGroup>
  <Card title="Client guide" icon="terminal" href="/docs/guides/client-guide">
    CLI flags, config file, and the full set of tunnel modes.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/docs/guides/architecture">
    How HTTP / TCP / UDP / P2P tunnels flow through the system.
  </Card>

  <Card title="UDP tunnels" icon="radio" href="/docs/reference/udp-tunnels">
    Forward UDP datagrams (game servers, DNS, QUIC, VoIP) to a public port.
  </Card>

  <Card title="P2P tunnels" icon="network" href="/docs/reference/p2p-tunnels">
    Direct peer-to-peer connections with NAT hole punching and relay fallback.
  </Card>
</CardGroup>


# P2P Tunnels — direct peer-to-peer connections without an exit node
Source: https://rustunnel.com/docs/reference/p2p-tunnels

rustunnel P2P tunnels connect two clients directly with NAT hole punching over QUIC — no exit node, no relay tax once direct mode is established. Covers relay mode, direct mode, NAT classification, hole punching, and automatic fallback.

This page covers **rustunnel P2P tunnels** — direct peer-to-peer connections between two clients **without an exit node** in the data path. Once the two peers complete NAT hole punching, traffic flows directly between them over QUIC; the rustunnel server only signals during the handshake. If hole punching fails (symmetric NAT, restrictive firewall), rustunnel transparently falls back to relayed mode.

This allows two machines — neither with a public IP — to communicate through the rustunnel server, with an optional upgrade to a direct connection that bypasses the server entirely.

## Concepts

A P2P tunnel connects two rustunnel clients:

* **Publisher** — the client exposing a local service (e.g., a game server on port 27015). Registers a named tunnel with a shared secret.
* **Subscriber** — the client connecting to the publisher's service. Listens on a local port (e.g., 8000) and forwards incoming TCP connections through the tunnel.
* **Shared secret** — a password both sides must know. The SHA-256 hash is sent to the server for verification; the plaintext never leaves the client.

```text theme={null}
App -> Subscriber (localhost:8000) --tunnel--> Publisher (localhost:27015) -> Service
```

Unlike HTTP/TCP tunnels, P2P tunnels don't require a public port or subdomain on the server. The server acts as a signaling relay and (optionally) a data relay.

***

## Connection Modes

P2P tunnels support two modes:

| Mode        | Data path                                                             | Latency              | Server load    | Metered |
| ----------- | --------------------------------------------------------------------- | -------------------- | -------------- | ------- |
| **Relayed** | App -> Subscriber -> Server -> Publisher -> Service                   | Higher (two WS hops) | Full bandwidth | Yes     |
| **Direct**  | App -> Subscriber -> Publisher -> Service (via UDP hole punch + QUIC) | Lower (peer-to-peer) | Signaling only | No      |

The mode is selected automatically based on NAT compatibility. If direct mode fails or isn't possible, the connection transparently falls back to relayed mode.

***

## Server-Relayed Mode

This is the default mode and always works regardless of NAT type or firewall configuration.

### Connection flow

<Steps>
  <Step title="Publisher registers">
    The publisher connects to the server and registers a P2P tunnel with a name (e.g., `my-game`) and a SHA-256 hash of the shared secret.
  </Step>

  <Step title="Subscriber accepts a local connection">
    The subscriber listens on its local port (e.g., 8000). When an app connects, the subscriber sends a `P2pConnect` request to the server with the tunnel name and secret hash.
  </Step>

  <Step title="Server verifies and creates relay">
    The server looks up the publisher by name, verifies the secret hash matches, then sends `NewConnection` to both the publisher and subscriber sessions.
  </Step>

  <Step title="Both sides open yamux streams">
    The publisher opens a yamux stream and connects to its local service (e.g., `localhost:27015`). The subscriber bridges the already-accepted TCP connection with its yamux stream.
  </Step>

  <Step title="Server bridges the streams">
    The server runs `copy_bidirectional` between the publisher's and subscriber's yamux streams. Data flows bidirectionally until either side disconnects.
  </Step>
</Steps>

<Info>
  Each incoming connection to the subscriber's local port creates a new relay. Multiple concurrent connections are supported, each with its own yamux stream pair.
</Info>

### Key details

* **On-demand relay**: The relay is established per-connection, not at startup. Each app connection to the subscriber's local port triggers a new `P2pConnect`.
* **Yamux multiplexing**: Both clients maintain persistent WebSocket connections to the server. Each relay uses a separate yamux stream over these existing connections.
* **No public ports needed**: Neither client needs to accept inbound connections from the internet.

***

## Direct Mode (NAT Hole Punching)

Direct mode bypasses the server for the data path. After an initial signaling exchange through the server, the publisher and subscriber establish a direct UDP connection using NAT hole punching, then upgrade it to a QUIC session for reliable, encrypted transport.

<Note>
  Direct mode is enabled per-server via the `[p2p]` config section (`direct_enabled = true`). When enabled, the server automatically attempts hole punching for compatible NAT pairs. The relay is always available as a fallback.
</Note>

### Why direct mode matters

* **Lower latency**: Data travels directly between peers instead of bouncing through the server.
* **Lower server cost**: The server only handles signaling (\~1 KB), not the full data stream.
* **Better for real-time applications**: Game servers, VoIP, and live streaming benefit from reduced round-trip time.

***

## NAT Classification via STUN

Before attempting hole punching, each client determines its NAT type using the **STUN protocol** (Session Traversal Utilities for NAT).

### How STUN probing works

The client sends a STUN Binding Request to **two different STUN servers**. Each server replies with the client's **mapped address** — the public IP and port the server saw the request come from.

By comparing the two responses, the client classifies its NAT:

| STUN Server A reply  | STUN Server B reply  | NAT type                             |
| -------------------- | -------------------- | ------------------------------------ |
| `1.2.3.4:5000`       | `1.2.3.4:5000`       | **Cone NAT** (traversable)           |
| `1.2.3.4:5000`       | `1.2.3.4:6001`       | **Symmetric NAT** (hard to traverse) |
| Public IP = Local IP | Public IP = Local IP | **Open** (no NAT)                    |
| No response          | No response          | **Unknown** (use relay)              |

### NAT types explained

| NAT Type                 | Description                                                                             | Hole punch success |
| ------------------------ | --------------------------------------------------------------------------------------- | ------------------ |
| **Open**                 | No NAT — client has a public IP                                                         | \~100%             |
| **Full Cone**            | Same public mapping for all destinations; any external host can send to the mapped port | \~100%             |
| **Restricted Cone**      | Same mapping, but only hosts the client has sent to can reply                           | \~95%              |
| **Port-Restricted Cone** | Same mapping, restricted by both IP and port                                            | \~90%              |
| **Symmetric**            | Different mapping for each destination (port changes per target)                        | \~10-60%           |

The key distinction: **Cone NATs** reuse the same public port for all outbound connections, making the mapped address predictable. **Symmetric NATs** assign a different port per destination, making prediction unreliable.

<Tip>
  STUN probing takes \~100ms (two UDP round trips) and happens once at tunnel registration time. It's cheap and non-invasive.
</Tip>

***

## Hole Punching Strategy

The server classifies the NAT pair and selects one of three strategies:

### Strategy 1: Direct Exchange (Cone + Cone)

Both peers have predictable mapped addresses. Both send a UDP probe to the other's mapped address. The first probe "punches" the hole in each NAT by creating an outbound mapping. The second probe passes through.

**Success rate: \~95%**

### Strategy 2: Port Prediction (Cone + Symmetric)

The Cone peer has a predictable address. The Symmetric peer's port changes per destination, but the server observes the port increment pattern from the STUN probes and predicts the next port range. The Cone peer sends probes to the predicted range.

**Success rate: \~60-70%**

### Strategy 3: Skip (Symmetric + Symmetric)

Both peers have unpredictable port mappings. Brute-force probing has a success rate under 10% and can trigger firewall alarms.

**Decision: fall back to relay immediately.** No hole punching attempted, no delay.

### Decision matrix

| Publisher NAT | Subscriber NAT | Strategy          | Expected success |
| ------------- | -------------- | ----------------- | ---------------- |
| Open/Cone     | Open/Cone      | Direct Exchange   | \~95%            |
| Cone          | Symmetric      | Port Prediction   | \~60-70%         |
| Symmetric     | Cone           | Port Prediction   | \~60-70%         |
| Symmetric     | Symmetric      | **Skip -> Relay** | N/A              |
| Unknown       | Any            | **Skip -> Relay** | N/A              |

***

## Automatic Fallback

When direct mode is attempted but fails, the connection transparently falls back to server relay:

```text theme={null}
1. Subscriber connects via P2pConnect
2. Server classifies NAT pair
3. If traversable:
   a. Server sends hole-punch instructions
   b. Peers send UDP probes (5-second timeout)
   c. Success -> QUIC session -> direct mode
   d. Failure -> relay mode
4. If not traversable:
   a. Relay immediately (no delay)
```

From the user's perspective:

| Outcome                            | Connection time | Latency            |
| ---------------------------------- | --------------- | ------------------ |
| Direct succeeded                   | \~1-2 seconds   | Low (peer-to-peer) |
| Direct failed (timeout)            | \~6-7 seconds   | Normal (relay)     |
| Direct skipped (incompatible NATs) | \~1-2 seconds   | Normal (relay)     |

The subscriber never needs to know which mode is active. The CLI command is identical in all cases.

***

## Security

### Shared secret authentication

1. Client computes `SHA-256(secret)` locally.
2. Only the **hash** is sent to the server.
3. The server compares hashes. Mismatch = connection rejected.
4. The plaintext secret never leaves the client.

### Transport encryption

| Mode        | Encryption                 | Server visibility                                   |
| ----------- | -------------------------- | --------------------------------------------------- |
| **Relayed** | TLS (WebSocket)            | Server can see plaintext (same as HTTP/TCP tunnels) |
| **Direct**  | QUIC (TLS 1.3, end-to-end) | Server cannot see plaintext                         |

### Tunnel name visibility

P2P tunnel names are visible to the server. Anyone who knows both the tunnel name and the shared secret can connect. Use strong, unique secrets for production.

***

## Billing and Metering

| Mode        | Metered by server?        | Billing                              |
| ----------- | ------------------------- | ------------------------------------ |
| **Relayed** | Yes                       | Per-byte, same as TCP tunnels        |
| **Direct**  | No (data bypasses server) | Informational only (client-reported) |

***

## CLI Usage

### Publisher (expose a service)

```bash theme={null}
rustunnel p2p 27015 --name my-game --secret "shared-secret-123"
```

Exposes `localhost:27015` as a P2P tunnel named `my-game`.

### Subscriber (connect to a service)

```bash theme={null}
rustunnel p2p 8000 --target my-game --secret "shared-secret-123"
```

Listens on `localhost:8000`. Any TCP connection to that port is forwarded through the tunnel to the publisher's `localhost:27015`.

### Config file

```yaml theme={null}
tunnels:
  # Publisher
  gameserver:
    proto: p2p
    local_port: 27015
    p2p_name: my-game
    p2p_secret: shared-secret-123

  # Subscriber
  connect:
    proto: p2p
    local_port: 8000
    p2p_target: my-game
    p2p_secret: shared-secret-123
```

### Error cases

| Error                                   | Cause                                           |
| --------------------------------------- | ----------------------------------------------- |
| `P2P tunnel name 'X' is already in use` | Another publisher is using this name            |
| `P2P tunnel 'X' not found`              | No publisher registered with this name          |
| `invalid P2P secret`                    | Subscriber's secret doesn't match publisher's   |
| `P2P mode requires --name or --target`  | Neither publisher nor subscriber mode specified |

***

## See also

<CardGroup>
  <Card title="UDP Tunnels" icon="bolt" href="/docs/reference/udp-tunnels">
    Forward UDP datagrams (game servers, DNS, QUIC, VoIP) to a public port on the rustunnel server.
  </Card>

  <Card title="Load Balancing & Health Checks" icon="scale-balanced" href="/docs/reference/load-balancing">
    Run multiple backends behind one subdomain or TCP port with automatic failover.
  </Card>

  <Card title="Client Guide" icon="terminal" href="/docs/guides/client-guide">
    Every flag and config option for the rustunnel CLI client.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/docs/guides/architecture">
    How HTTP / TCP / UDP / P2P tunnels flow through the system.
  </Card>
</CardGroup>


# UDP Tunnels in rustunnel — Rust-based UDP forwarding for game servers, DNS, and QUIC
Source: https://rustunnel.com/docs/reference/udp-tunnels

rustunnel UDP tunnels forward datagrams from a public port on the tunnel server to a local UDP service — game servers, DNS resolvers, QUIC endpoints, VoIP. Covers sessions, length-prefixed framing, server configuration, and CLI usage.

This page documents **UDP tunnels in rustunnel**, our Rust-based UDP forwarding implementation. A UDP tunnel exposes a local UDP service — a game server, DNS resolver, QUIC endpoint, VoIP service — on a public port on the rustunnel server, forwarding datagrams bidirectionally between remote clients and the local service over the same multiplexed control connection that powers HTTP and TCP tunnels. For TCP-style direct connections see [P2P tunnels](/docs/reference/p2p-tunnels); for HTTP load-balanced groups see [Load Balancing & Health Checks](/docs/reference/load-balancing).

## Concepts

UDP is connectionless, so there is no persistent "connection" to forward. Instead, rustunnel tracks **sessions** — one per unique remote source address (`IP:port`) — and forwards datagrams in both directions for as long as the session is active.

```text theme={null}
Remote client -> server:20100 (UDP) --tunnel--> Client -> localhost:27015 (UDP) -> Service
```

* **Public port** — allocated from a dedicated UDP port range on the server (separate from the TCP tunnel pool).
* **Session** — identified by the remote client's source `IP:port`. Each unique source gets its own yamux stream to the client and its own locally bound UDP socket.
* **Idle timeout** — sessions are reaped after 60 seconds of inactivity.

<Info>
  Unlike HTTP/TCP tunnels, there is no long-lived connection to track. Sessions are created on first datagram and expire on inactivity.
</Info>

***

## Connection Flow

<Steps>
  <Step title="Client registers a UDP tunnel">
    The rustunnel client sends `RegisterTunnel` with `protocol = Udp`. The server allocates a port from `udp_port_range` and replies with `TunnelRegistered { public_port }`.
  </Step>

  <Step title="Remote client sends a datagram">
    A remote UDP client sends a datagram to the allocated public port. The server's UDP edge looks up a session keyed by the datagram's source address.
  </Step>

  <Step title="Server creates a session on first datagram">
    If no session exists, the server creates one, buffers the datagram (up to 64 packets), and sends `NewConnection { conn_id, protocol: Udp }` to the client over the control-plane WebSocket.
  </Step>

  <Step title="Client opens a yamux stream">
    The client opens a new yamux stream for the `conn_id`, binds a local UDP socket, and `connect()`s it to the local service address (e.g., `127.0.0.1:27015`).
  </Step>

  <Step title="Bidirectional datagram forwarding">
    The server forwards the buffered and subsequent datagrams into the yamux stream. The client writes them to the local service and copies replies back through the stream. The server delivers replies to the original source address.
  </Step>
</Steps>

Subsequent datagrams from the same remote source reuse the existing session and yamux stream. Datagrams from a new source create a new session.

***

## Transport and Framing

UDP datagrams ride over the same yamux-over-WebSocket tunnel used by HTTP and TCP. Because yamux is a reliable byte stream and UDP is message-oriented, rustunnel preserves datagram boundaries with a simple length-prefixed frame:

```text theme={null}
[ 4-byte u32 big-endian length ][ N-byte payload ]
```

* No encoding overhead beyond the 4-byte header.
* Maximum payload is bounded by UDP itself (65,507 bytes after the IP/UDP header).
* Framing overhead is **not** counted toward `bytes_proxied` — only raw payload bytes are metered.

<Tip>
  UDP tunnels reuse the client's existing WebSocket connection to the server. No new sockets are opened from client to server for UDP.
</Tip>

***

## Sessions

A UDP session holds:

| Field                               | Purpose                                                                |
| ----------------------------------- | ---------------------------------------------------------------------- |
| Forwarding channel                  | Edge listener pushes datagrams into the yamux stream                   |
| Last-activity timestamp             | Used by the reaper to detect idle sessions                             |
| Initial buffer (up to 64 datagrams) | Holds packets that arrive while the client is opening the yamux stream |

A reaper task runs every 10 seconds and closes any session idle for more than **60 seconds**. Because UDP has no FIN, this is how rustunnel decides when a session has ended.

***

## Server Configuration

UDP tunnels require a dedicated port range in `server.toml`. It must not overlap with `tcp_port_range`, and the ports must be reachable through the host firewall.

```toml theme={null}
[limits]
# Inclusive [low, high] port range reserved for UDP tunnels.
# Each active UDP tunnel consumes one port from this range.
# Set to [0, 0] to disable UDP tunnels entirely.
udp_port_range = [20100, 20199]
```

Open the range in the host firewall:

```bash theme={null}
ufw allow 20100:20199/udp comment "rustunnel UDP tunnels"
```

<Warning>
  `udp_port_range` and `tcp_port_range` must not overlap. Setting `udp_port_range = [0, 0]` disables UDP tunnel registration entirely — any client attempting to register a UDP tunnel will get an error.
</Warning>

***

## CLI Usage

Expose a local UDP service:

```bash theme={null}
# Expose a game server on udp/27015
rustunnel udp 27015 --token YOUR_TOKEN

# Pin to a specific region
rustunnel udp 27015 --region eu --token YOUR_TOKEN

# Local development against a self-hosted server
rustunnel udp 53 --server localhost:4040 --insecure --token dev-secret-change-me
```

On success the client prints the allocated public UDP endpoint:

```text theme={null}
UDP tunnel ready: udp://eu.edge.rustunnel.com:20100 -> localhost:27015
```

Any datagram sent to that public `host:port` is forwarded to your local service, and replies are returned to the original sender.

***

## Config File

In `~/.rustunnel/config.yml`:

```yaml theme={null}
tunnels:
  gameserver:
    proto: udp
    local_port: 27015

  dns:
    proto: udp
    local_port: 53
```

Start all configured tunnels with `rustunnel start`.

***

## Limitations and Notes

| Topic                   | Notes                                                                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Datagram size**       | Up to 65,507 bytes. Payloads exceeding the path MTU will fragment at the IP layer; rustunnel does not perform application-level segmentation.             |
| **Per-source sessions** | Each unique `source_ip:source_port` creates its own session. NATs that rewrite ports aggressively (some mobile carriers) can produce many short sessions. |
| **Idle reaping**        | 60-second inactivity timeout. Services that rely on very infrequent keepalives may need to send periodic traffic.                                         |
| **Rate limiting**       | Per-tunnel rate limits apply; each datagram counts as one request against `rate_limit_rps`.                                                               |
| **Metering**            | `bytes_proxied` counts raw UDP payload only; the 4-byte framing header is excluded.                                                                       |
| **No TLS**              | UDP is forwarded as-is. For encryption, use DTLS, QUIC, or WireGuard inside the tunnel.                                                                   |

***

## Troubleshooting

| Symptom                                                | Likely cause                                                                                                            |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `udp_port_range is disabled` on registration           | `udp_port_range = [0, 0]` in `server.toml`. Set a real range.                                                           |
| Datagrams reach the server but not the local service   | Local firewall blocking the loopback UDP port, or the service isn't actually listening on UDP (`ss -ulnp` to confirm).  |
| Replies from the local service are never seen remotely | The service isn't replying to the packet's source — make sure it replies to the datagram source, not a hard-coded peer. |
| New session every few packets from the same client     | Source NAT rewriting the client's port — a client-network issue, often unavoidable on mobile.                           |
| Connection "drops" after \~60 seconds of idle          | Idle reaper closed the session. Send a keepalive or reopen on demand.                                                   |
| Public UDP port not reachable from the internet        | Host firewall isn't open for `udp_port_range`. Run `ufw allow 20100:20199/udp`.                                         |

***

## Related pages

<CardGroup>
  <Card title="P2P tunnels" icon="network" href="/docs/reference/p2p-tunnels">
    Connect two clients directly with NAT hole punching over QUIC, with automatic relay fallback.
  </Card>

  <Card title="Load balancing and health checks" icon="route" href="/docs/reference/load-balancing">
    Run multiple backends behind one subdomain or TCP port with automatic failover.
  </Card>

  <Card title="Client guide" icon="terminal" href="/docs/guides/client-guide">
    Every command, flag, and config option for the rustunnel CLI client.
  </Card>

  <Card title="Self-hosting" icon="server" href="/docs/guides/self-hosting">
    Run your own rustunnel server and configure port ranges, TLS, and firewall rules.
  </Card>
</CardGroup>