rustunnel

rustunnel

成長に合わせてスケールするオープンソースのトンネルです。アイドル時間に料金を支払う必要はありません。安全で、Rust ならではの高速性を備え、従量課金制です。

ローカルサービスを、TLS 終端、HTTP/TCP プロキシ、ライブダッシュボード、Prometheus メトリクス、監査ログを備えた暗号化 WebSocket 接続を介して、パブリックサーバーに公開できます。

セルフホストすることも、マネージドサービスを利用することもできます。

AI エージェントを使用していますか？ rustunnel には MCP サーバーが付属しています。Cursor ならワンクリックでセットアップできます（その後、API トークンを追加してください）。

Claude Code、Claude Desktop、Windsurf などについては、エージェント連携ガイドまたは rustunnel.com/agents.md のエージェントマニュアルをご覧ください。

---

目次

• ホステッドサービス
• アーキテクチャの概要
• 要件
• ローカル開発環境のセットアップ
  • ビルド
  • テストの実行
  • サーバーをローカルで実行
  • クライアントをローカルで実行
  • Git フック
• 本番環境へのデプロイ（Ubuntu / systemd）
  • 1 — 依存関係をインストール
  • 2 — リリースバイナリをビルド
  • 3 — システムユーザーとディレクトリを作成
  • 4 — サーバーバイナリをインストール
  • 5 — サーバー設定ファイルを作成
  • 6 — TLS 証明書（Let's Encrypt + Cloudflare）
  • 7 — systemd サービスをセットアップ
  • 8 — ファイアウォールポートを開放
  • 9 — サーバーの稼働を確認
  • サーバーの更新
• Docker でのデプロイ · 完全ガイド
• クライアントの設定
  • インストール
  • セットアップウィザード
  • クイックスタート（CLI フラグ）
  • 機械可読な出力（--json）
  • 設定ファイル
  • トークン管理
• ポート一覧
• 設定ファイルのリファレンス（サーバー）
• REST API
• AI エージェント連携（MCP サーバー）
  • OpenClaw スキル
• モニタリング
• ロードマップ
• コントリビューション
• ライセンス
• 連絡先

---

ホステッドサービス

自分でサーバーを運用せずに rustunnel を利用できます。すぐに接続できるパブリックエッジサーバーのグローバルなフリートを運用しています。

利用可能なリージョン

リージョン ID	サーバー	場所	コントロールプレーン	ステータス
eu	eu.edge.rustunnel.com	ヘルシンキ、FI	:4040	稼働中
us	us.edge.rustunnel.com	ヒルズボロ、OR	:4040	稼働中
ap	ap.edge.rustunnel.com	シンガポール	:4040	稼働中

クライアントはデフォルトで最も近いリージョンを自動選択します。特定のリージョンに接続するには、--region <id> を使用します。従来のアドレス edge.rustunnel.com は eu.edge.rustunnel.com の CNAME であり、後方互換性のため引き続き利用できます。

認証トークンの取得

rustunnel.com で無料アカウントに登録できます。ウェイトリストへの登録や手動承認は不要です。

1. rustunnel.com でアカウントを作成します
2. Dashboard → API Keys に移動し、トークンを作成します
3. トークンをコピーします。トークンが表示されるのは一度だけです

プラン：

プラン	料金	トンネル	カスタムサブドメイン	TLS/HTTPS
Free	$0	最大 3	—	✓
従量課金制	月額 $3 以上 + $0.10/GB	無制限	✓	✓
セルフホスト	無料（独自サーバーを実行）	無制限	✓	✓

無料プランは利用を始めるのに最適です。カスタムサブドメインや無制限のトンネルが必要になったら、ダッシュボードからいつでも従量課金制にアップグレードできます。

ホステッドサーバーですぐに始める

トークンを取得したら、セットアップウィザードを実行します。

rustunnel setup
# Region [auto / eu / us / ap / self-hosted] (default: auto): (press Enter)
#   Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
#   Server set to: eu.edge.rustunnel.com:4040
# Auth token: <paste your token>

次に、ローカルサービスを公開します。

# HTTP tunnel — auto-selects the nearest region
rustunnel http 3000

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

# Custom subdomain
rustunnel http 3000 --subdomain myapp

# TCP tunnel — e.g. expose a local database
rustunnel tcp 5432

# UDP tunnel — e.g. expose a game server
rustunnel udp 27015

# P2P tunnel — expose a service to another rustunnel client
rustunnel p2p 27015 --name my-game --secret "shared-secret"

# P2P tunnel — connect to a peer's service
rustunnel p2p 8000 --target my-game --secret "shared-secret"

トンネルが確立すると、クライアントに公開 URL がすぐに表示されます。

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

---

アーキテクチャの概要

                        ┌──────────────────────────────────────────┐
                        │           rustunnel-server               │
                        │                                          │
Internet ──── :80 ─────▶│  HTTP edge (301 → HTTPS)                 │
Internet ──── :443 ────▶│  HTTPS edge  ──▶ yamux stream ──▶ client │
Client ───── :4040 ────▶│  Control-plane WebSocket (TLS)           │
Browser ──── :8443 ────▶│  Dashboard UI + REST API                 │
Prometheus ─ :9090 ────▶│  Metrics endpoint                        │
Internet ── :20000+ ───▶│  TCP tunnel ports (one per TCP tunnel)   │
                        └──────────────────────────────────────────┘
                                          │ yamux multiplexed streams
                                          ▼
                              ┌─────────────────────┐
                              │   rustunnel client   │
                              │  (developer laptop)  │
                              └──────────┬──────────┘
                                         │ localhost
                                         ▼
                                ┌────────────────┐
                                │  local service  │
                                │  e.g. :3000    │
                                └────────────────┘

---

必要条件

ビルドする場合

必要条件	バージョン	備考
Rust ツールチェーン	1.76+	rustup からインストールします
pkg-config	任意	reqwest（TLS）に必要です
libssl-dev	任意	Debian/Ubuntu の場合：apt install libssl-dev
Node.js + npm	18+	ダッシュボード UI を再ビルドする場合のみ必要です

本番環境でサーバーを実行する場合

必要条件	備考
Linux（Ubuntu 22.04 以降）	systemd サービスが含まれています
TLS 証明書 + 秘密鍵	PEM 形式（Let's Encrypt を推奨）
パブリック IP / DNS	HTTP トンネルにはワイルドカード DNS *.tunnel.yourdomain.com → server IP が必要です

---

ローカル開発環境のセットアップ

ビルド

# Clone the repository
git clone https://github.com/joaoh82/rustunnel.git
cd rustunnel

# Compile all workspace crates (debug mode)
cargo build --workspace

# Or use the Makefile shortcut
make build

テストの実行

統合テストスイートはランダムなポートで実際のサーバーを起動し、認証、HTTP トンネル、TCP トンネル、再接続のロジックをテストします。実行には、PostgreSQL インスタンスが稼働している必要があります。

# Start the local PostgreSQL container (once per machine, persists across reboots)
make db-start

# Full suite (unit + integration)
make test

# With output visible
TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test \
  cargo test --workspace -- --nocapture

# Stop PostgreSQL when you no longer need it
make db-stop

make db-start は deploy/docker-compose.dev-deps.yml を実行し、localhost:5432 で Postgres 16 コンテナを起動します。make test ターゲットは TEST_DATABASE_URL を自動的に設定します。cargo test を直接実行する場合は、先に変数をエクスポートしてください。

export TEST_DATABASE_URL=postgres://rustunnel:test@localhost:5432/rustunnel_test

サーバーをローカルで実行する

ローカルテスト用に自己署名証明書を生成します。

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"

ローカル用の設定ファイルが deploy/local/server.toml としてリポジトリに含まれています。 上記の自己署名証明書のパスを参照し、利便性のため認証は無効になっています。 この設定ファイルを直接指定してサーバーを起動します。

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

deploy/local/server.toml の主な設定：

設定	値
ドメイン	localhost
HTTP エッジ	:8080
HTTPS エッジ	:8443
コントロールプレーン	:4040
ダッシュボード	:4041
認証トークン	dev-secret-change-me
認証が必要	false
TLS 証明書	/tmp/rustunnel-dev/cert.pem
TLS 鍵	/tmp/rustunnel-dev/key.pem
データベース	/tmp/rustunnel-dev/rustunnel.db

クライアントをローカルで実行する

サーバーが稼働したら、ローカルサービス（ポート 3000 で動作するサービスなど）を公開します。

# HTTP tunnel
cargo run -p rustunnel-client -- http 3000 \
  --server localhost:4040 \
  --token dev-secret-change-me \
  --insecure

# TCP tunnel
cargo run -p rustunnel-client -- tcp 5432 \
  --server localhost:4040 \
  --token dev-secret-change-me \
  --insecure

--insecure は TLS 証明書の検証をスキップします。ローカルで自己署名証明書を使用する場合に必要です。本番サーバーに対してこのフラグを使用しないでください。

クライアントに公開 URL が表示されます。例：

http tunnel  →  http://abc123.localhost:8080
tcp  tunnel  →  tcp://localhost:20000

HTTP トンネルをローカルでテストする

トンネル URL ではサブドメインを使用します（例：http://abc123.localhost:8080）。 ブラウザーはデフォルトでは *.localhost サブドメインを解決できないため、次の 2 つの方法があります。

オプション A — Host ヘッダーを指定して curl を実行する（セットアップ不要）

curl -v -H "Host: abc123.localhost" http://localhost:8080/

オプション B — dnsmasq を使ったワイルドカード DNS（ブラウザーからアクセス可能）

# Install and configure dnsmasq to resolve *.localhost → 127.0.0.1
brew install dnsmasq
echo "address=/.localhost/127.0.0.1" | sudo tee -a $(brew --prefix)/etc/dnsmasq.conf
sudo brew services start dnsmasq

# Tell macOS to use dnsmasq for .localhost queries
sudo mkdir -p /etc/resolver
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/localhost

その後、ブラウザーで http://abc123.localhost:8080 にアクセスします（ローカル設定ではポート 80 ではなく 8080 を使用するため、:8080 を含めてください）。

Git フック

CI のチェック手順（フォーマットチェック＋Clippy）と同等の処理を行う pre-push フックが .githooks/ に含まれています。クローン後に一度だけ、次を実行して有効にしてください。

make install-hooks

有効にすると、以降は git push のたびに次の処理が自動的に実行されます。

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

どちらかのチェックに失敗すると push は中止され、リモートブランチが正常な状態に保たれます。

---

本番環境へのデプロイ（Ubuntu / systemd）

以下の手順は、次の環境へのデプロイを想定しています。

• ドメイン：edge.rustunnel.com
• ワイルドカード DNS：*.edge.rustunnel.com → <server IP>
• TLS 証明書：Certbot と Cloudflare の DNS チャレンジを使用した Let's Encrypt

1 — 依存関係をインストールする

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

Rust をインストールします（root ではなく、ビルドユーザーとして実行してください）。

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

2 — リリースバイナリをビルドする

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

バイナリの配置先：

• target/release/rustunnel-server
• target/release/rustunnel

3 — システムユーザーとディレクトリを作成する

useradd --system --no-create-home --shell /usr/sbin/nologin rustunnel

mkdir -p /etc/rustunnel /var/lib/rustunnel
chown rustunnel:rustunnel /var/lib/rustunnel
chmod 750 /var/lib/rustunnel

4 — サーバーバイナリをインストールする

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

または、Makefile のターゲットを使用します（ビルド、インストール、systemd のセットアップを実行します）。

sudo make deploy

5 — PostgreSQL をセットアップする

rustunnel は共有状態（トークン、トンネル履歴、監査ログ）の管理に PostgreSQL を必要とします。

apt install -y postgresql postgresql-contrib

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

専用のデータベースとユーザーを作成します。

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

ヒント： マネージド PostgreSQL（例：AWS RDS、DigitalOcean Managed Database、Supabase）を使用する場合は、上記の apt install 手順を省略し、次の手順の設定に使用する接続 URL を控えてください。

スキーマのマイグレーションはサーバーの起動時に自動的に実行されます。手動で SQL を実行する必要はありません。

6 — サーバー設定ファイルを作成する

以下の内容で /etc/rustunnel/server.toml を作成します。 your-admin-token-here を、推測されにくいランダムなシークレット（例：openssl rand -hex 32）に置き換えてください。

# /etc/rustunnel/server.toml

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

# Ports for incoming tunnel traffic (requires CAP_NET_BIND_SERVICE or root).
http_port    = 80
https_port   = 443

# Control-plane WebSocket port — clients connect here.
control_port = 4040

# Dashboard UI and REST API port.
dashboard_port = 8443

# Allowed CORS origin for the dashboard UI.
# Set to the URL where you serve the dashboard-ui (e.g. http://localhost:3000 for local dev).
dashboard_origin = "http://localhost:3000"

# ── TLS ─────────────────────────────────────────────────────────────────────
[tls]
# Paths written by Certbot (see step 6).
cert_path = "/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem"
key_path  = "/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem"

# Set acme_enabled = true only if you want rustunnel to manage certs itself
# via the ACME protocol (requires Cloudflare credentials below).
# When using Certbot (recommended), leave this false.
acme_enabled = false

# ── Auth ─────────────────────────────────────────────────────────────────────
[auth]
# Strong random secret — used both as the admin token and for client auth.
# Generate: openssl rand -hex 32
admin_token  = "your-admin-token-here"
require_auth = true
# Failed auth attempts per source IP per minute before rejection (0 = off).
max_failed_auth_per_minute = 10

# ── Database ─────────────────────────────────────────────────────────────────
[database]
# PostgreSQL connection URL — the database and user must exist before starting
# the server (see the PostgreSQL setup step above).  Schema migrations run
# automatically on first start.
url = "postgresql://rustunnel:CHANGE_ME@localhost:5432/rustunnel"

# Per-region SQLite file for captured HTTP request bodies.
# The directory must be writable by the rustunnel user.
captured_path = "/var/lib/rustunnel/captured.db"

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

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

# ── Limits ───────────────────────────────────────────────────────────────────
[limits]
# Maximum tunnels a single authenticated session may register.
max_tunnels_per_session = 10

# Maximum simultaneous proxied connections per tunnel (semaphore).
max_connections_per_tunnel = 100

# Per-tunnel request rate limit (requests/second).
rate_limit_rps = 100

# Per-source-IP rate limit (requests/second). Set to 0 to disable.
ip_rate_limit_rps = 100

# Maximum size of a proxied HTTP request body (bytes). Default: 10 MB.
request_body_max_bytes = 10485760

# Inclusive port range reserved for TCP tunnels.
# Each active TCP tunnel consumes one port from this range.
tcp_port_range = [20000, 20099]

# Inclusive port range reserved for UDP tunnels.
# Each active UDP tunnel consumes one port from this range.
# Must not overlap with tcp_port_range. Set to [0, 0] to disable UDP tunnels.
udp_port_range = [20100, 20199]

ファイルを保護します。

chown root:rustunnel /etc/rustunnel/server.toml
chmod 640 /etc/rustunnel/server.toml

7 — TLS 証明書（Let's Encrypt + Cloudflare）

Cloudflare の認証情報ファイルを作成します。

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

ベースドメインとワイルドカードの両方を含む証明書をリクエストします（HTTP サブドメイントンネルに必要です）。

certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
  -d "edge.rustunnel.com" \
  -d "*.edge.rustunnel.com" \
  --agree-tos \
  --email [email protected]

Certbot は証明書を次の場所に書き込みます。

/etc/letsencrypt/live/edge.rustunnel.com/fullchain.pem
/etc/letsencrypt/live/edge.rustunnel.com/privkey.pem

これらのパスは、上記の設定で指定済みです。Certbot は systemd タイマーによる自動更新を設定します。

rustunnel は起動時にディスクから TLS 証明書を読み込むため、証明書の更新後に再起動する必要があります。 これを自動化するため、Certbot の deploy フックを追加します。

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

rustunnel サービスユーザーが証明書を読み取れるようにします。

# Grant read access to the live/ and archive/ directories
chmod 755 /etc/letsencrypt/{live,archive}
chmod 640 /etc/letsencrypt/live/edge.rustunnel.com/*.pem
chgrp rustunnel /etc/letsencrypt/live/edge.rustunnel.com/*.pem
chgrp rustunnel /etc/letsencrypt/archive/edge.rustunnel.com/*.pem
chmod 640 /etc/letsencrypt/archive/edge.rustunnel.com/*.pem

8 — systemd サービスをセットアップする

# Copy the unit file from the repository
install -Dm644 deploy/rustunnel.service /etc/systemd/system/rustunnel.service

systemctl daemon-reload
systemctl enable --now rustunnel.service

# Check it started
systemctl status rustunnel.service
journalctl -u rustunnel.service -f

9 — ファイアウォールのポートを開放する

ufw allow 80/tcp   comment "rustunnel HTTP edge"
ufw allow 443/tcp  comment "rustunnel HTTPS edge"
ufw allow 4040/tcp comment "rustunnel control plane"
ufw allow 8443/tcp comment "rustunnel dashboard"
ufw allow 9090/tcp comment "rustunnel Prometheus metrics"

# TCP tunnel port range (must match tcp_port_range in server.toml)
ufw allow 20000:20099/tcp comment "rustunnel TCP tunnels"

# UDP tunnel port range (must match udp_port_range in server.toml)
ufw allow 20100:20199/udp comment "rustunnel UDP tunnels"

10 — サーバーの稼働を確認する

# Health check — use dashboard_port from server.toml (default 8443 in production)
curl http://localhost:8443/api/status

# Confirm which ports the process is actually bound to
ss -tlnp | grep rustunnel-serve

# Startup banner is visible in the logs
journalctl -u rustunnel.service --no-pager | tail -30

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

ポートに関する注意： ポート 4040 はコントロールプレーンの WebSocket（クライアントが接続するポート）であり、ダッシュボードではありません。通常の HTTP でアクセスすると HTTP/0.9 が返されますが、これは想定どおりです。ダッシュボードは dashboard_port で利用できます。不明な場合は server.toml を確認してください。

サーバーの更新

最新のコードを取得し、ビルド、インストール、再起動を 1 つのコマンドで実行します。

cd ~/rustunnel && sudo make update-server

このコマンドは、git pull → cargo build --release → install → systemctl restart → systemctl status を実行します。

---

Docker によるデプロイ

ローカル開発（自己署名証明書）と本番 VPS（Let's Encrypt）の両方を対象とした Docker の完全なガイドは、 docs/docker-deployment.md にあります。

公開済みイメージを取得する

マルチアーキテクチャイメージ（linux/amd64 + linux/arm64）は、安定版リリースのたびに GitHub Container Registry に公開されます。ビルドは不要です。

# Latest stable, or pin a version (e.g. :0.8.1)
docker pull ghcr.io/joaoh82/rustunnel-server:latest

# Run it with your server config mounted at /etc/rustunnel/server.toml
docker run --rm \
  -p 80:80 -p 443:443 -p 4040:4040 -p 8443:8443 \
  -v "$PWD/deploy/server.toml:/etc/rustunnel/server.toml:ro" \
  ghcr.io/joaoh82/rustunnel-server:latest

クイックリファレンス（ソースからビルド）

# Build the image locally (includes Next.js dashboard + Rust server)
make docker-build

# Build and push a multi-arch image to GHCR (maintainers; needs buildx + ghcr login)
make docker-push

# Local development (self-signed cert, no auth required)
docker compose -f deploy/docker-compose.local.yml up

# Production VPS (requires deploy/server.toml to be configured first)
make docker-run

# Production + Prometheus + Grafana monitoring stack
make docker-run-monitoring

# Tail server logs
make docker-logs

# Stop everything
make docker-stop

ファイル

ファイル	用途
deploy/Dockerfile	マルチステージビルド：Node.js UI → Rust サーバー → スリムなランタイム
deploy/docker-compose.yml	本番環境用 Compose ファイル
deploy/docker-compose.local.yml	ローカル開発用 Compose ファイル
deploy/server.toml	本番環境用サーバー設定テンプレート
deploy/server.local.toml	ローカル開発用サーバー設定
deploy/prometheus.yml	Prometheus スクレイプ設定

---

クライアントの設定

インストール

オプション 1 — Homebrew（macOS および Linux、推奨）

brew tap joaoh82/rustunnel
brew install rustunnel

Homebrew ではビルド済みバイナリがインストールされるため、Rust ツールチェーンは不要です。 フォーミュラはリリースのたびに自動で更新されます。これにより、 rustunnel（CLI クライアント）と rustunnel-mcp（AI エージェント連携用の MCP サーバー）の両方がインストールされます。

オプション 2 — ビルド済みバイナリ

お使いのプラットフォーム用のアーカイブを 最新の GitHub リリースからダウンロードし、 展開して、rustunnel バイナリを $PATH 上のディレクトリに移動します。

# Example for macOS Apple Silicon
curl -L https://github.com/joaoh82/rustunnel/releases/latest/download/rustunnel-<version>-aarch64-apple-darwin.tar.gz \
  | tar xz
sudo install -Dm755 rustunnel /usr/local/bin/rustunnel

利用可能なターゲット：

プラットフォーム	アーカイブ
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

オプション 3 — ソースからビルド

Rust 1.76 以降が必要です。

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

# Or via make
make deploy-client

セットアップウィザード

設定ファイルを作成する最も簡単な方法は、対話形式のセットアップウィザードを使うことです。

rustunnel setup

リージョンと認証トークンの入力を求められ、正しいサーバーアドレスとコメント付きの tunnels: 設定例セクションを含む ~/.rustunnel/config.yml が書き込まれます。

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

Region [auto / eu / us / ap / self-hosted] (default: auto):
  Selecting nearest region… eu 12ms · us 143ms · ap 311ms · → eu (Helsinki, FI) 12ms
  Server set to: eu.edge.rustunnel.com:4040

Auth token (leave blank to skip): rt_live_abc123...

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

特定のリージョン（eu、us、ap）を選択すると直接接続できます。または auto（デフォルト）を選ぶと、クライアントがすべてのリージョンを調べて最も近いリージョンを選択します。独自のサーバーを運用している場合は self-hosted を選択してください。その場合、ウィザードでサーバーアドレスの入力を求められます。

セットアップ後、rustunnel start を使うと設定ファイルで定義されているすべてのトンネルに接続できます。または、1 回限りのトンネルには rustunnel http <port> / rustunnel tcp <port> を使います。

クイックスタート（CLI フラグ）

# Expose a local HTTP service on port 3000 (auto-selects nearest region)
rustunnel http 3000 \
  --token YOUR_AUTH_TOKEN

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

# Use an explicit server address (bypasses region selection)
rustunnel http 3000 \
  --server edge.rustunnel.com:4040 \
  --token YOUR_AUTH_TOKEN

# Expose a local service with a custom subdomain
rustunnel http 3000 \
  --token YOUR_AUTH_TOKEN \
  --subdomain myapp

# Expose a local TCP service (e.g. a PostgreSQL database)
rustunnel tcp 5432 \
  --token YOUR_AUTH_TOKEN

# Disable automatic reconnection
rustunnel http 3000 --no-reconnect

機械可読出力（--json）

すべてのトンネル実行コマンド（http、tcp、udp、p2p、start）と token create は --json フラグを受け付けます。これを指定すると、標準出力には人間が読みやすい起動ボックスの代わりに NDJSON（1 行につき 1 つの JSON イベントオブジェクト）が出力されるため、スクリプトや AI エージェントから CLI を簡単に操作できます。

rustunnel http 3000 --json --token YOUR_AUTH_TOKEN

{"event":"tunnel_ready","protocol":"http","public_url":"https://myapp.eu.edge.rustunnel.com","local_port":3000,"local_host":"localhost","tunnel_id":"6f9a…","name":"myapp"}

イベント：

イベント	発生時	フィールド
tunnel_ready	トンネルが登録され、トラフィックを受け付けている	protocol、public_url、public_addr（host:port、tcp/udp のみ）、local_port、local_host、tunnel_id、name
reconnecting	接続が切断され、再試行がスケジュールされた	attempt、reason、delay_secs
reconnected	再接続に成功した（以降、新しい tunnel_ready イベントが続きます）	—
error	致命的なエラーが発生し、プロセスがコード 1 で終了する	code（config/auth/tunnel/connection/protocol/io）、message、hint
token_created	token create --json が成功した	token、name、id

診断情報は引き続き標準エラー出力に送られるため、標準出力は有効な NDJSON のままです。 http、tcp、udp、p2p コマンドでは、--token の代わりに RUSTUNNEL_TOKEN 環境変数から認証トークンを指定することもできます（start は設定ファイルからトークンを読み込みます）。

設定ファイル

デフォルトの場所：~/.rustunnel/config.yml

# ~/.rustunnel/config.yml

# Tunnel server address (host:control_port)
server: edge.rustunnel.com:4040

# Auth token (from server admin_token or a token created via the dashboard)
auth_token: YOUR_AUTH_TOKEN

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

# Named tunnels started with `rustunnel start`
tunnels:
  web:
    proto: http
    local_port: 3000
    subdomain: myapp      # optional — server assigns one if omitted

  db:
    proto: tcp
    local_port: 5432

設定ファイルからすべてのトンネルを起動します。

rustunnel start
# or with an explicit path
rustunnel start --config /path/to/config.yml

トークン管理

ホステッドサービス： rustunnel.com のダッシュボードで、Dashboard → API Keys からトークンを管理します。CLI コマンドを使わずに、トークンの作成、ラベル付け、失効ができます。

セルフホスト： ダッシュボード API を使って追加のトークンを作成します。

rustunnel token create \
  --name "ci-deploy" \
  --server your-server:8443 \
  --admin-token YOUR_ADMIN_TOKEN

または、curl を使います。

curl -s -X POST https://your-server:8443/api/tokens \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-deploy"}'

---

ポート一覧

ポート	プロトコル	用途
80	TCP	HTTP エッジ — HTTPS にリダイレクトします。また、ACME HTTP-01 チャレンジにも使用されます
443	TCP	HTTPS エッジ — TLS 終端トンネルの受け入れ
4040	TCP	コントロールプレーンの WebSocket — クライアントはここに接続します
8443	TCP	ダッシュボード UI と REST API
9090	TCP	Prometheus メトリクス（/metrics）
20000–20099	TCP	TCP トンネルの範囲（tcp_port_range で設定可能）
20100–20199	UDP	UDP トンネルの範囲（udp_port_range で設定可能）

---

設定ファイルのリファレンス（サーバー）

キー	型	デフォルト	説明
server.domain	string	—	トンネル URL のベースドメイン
server.http_port	u16	—	HTTP エッジポート
server.https_port	u16	—	HTTPS エッジポート
server.control_port	u16	—	WebSocket コントロールプレーンポート
server.dashboard_port	u16	4040	ダッシュボードのポート
tls.cert_path	string	—	TLS 証明書（PEM）へのパス
tls.key_path	string	—	TLS 秘密鍵（PEM）へのパス
tls.acme_enabled	bool	false	組み込みの ACME 更新を有効にします
tls.acme_email	string	""	ACME の連絡先メールアドレス
tls.acme_staging	bool	false	Let's Encrypt のステージング CA を使用します
tls.acme_account_dir	string	/var/lib/rustunnel	ACME の状態ディレクトリ
tls.cloudflare_api_token	string	""	Cloudflare DNS API トークン（環境変数 CLOUDFLARE_API_TOKEN の使用を推奨）
tls.cloudflare_zone_id	string	""	Cloudflare Zone ID（環境変数 CLOUDFLARE_ZONE_ID の使用を推奨）
auth.admin_token	string	—	マスター認証トークン
auth.require_auth	bool	—	認証されていないクライアントを拒否します
auth.max_failed_auth_per_minute	int	10	制御プレーンのハンドシェイクおよびダッシュボード API で、送信元 IP ごとに許可される 1 分あたりの認証失敗回数。この回数を超えると以降の試行は拒否されます。0 で無効になります
database.url	string	—	PostgreSQL 接続 URL（必須）
database.captured_path	string	/var/lib/rustunnel/captured.db	キャプチャされた HTTP リクエスト本文を保存する、リージョンごとの SQLite ファイル
server.dashboard_origin	string	""	ダッシュボード UI で許可する CORS オリジン（例：http://localhost:3000）
logging.level	string	—	trace / debug / info / warn / error
logging.format	string	—	json または pretty
logging.audit_log_path	string	null	監査ログ（JSON Lines）のパス。無効にするには省略します
limits.max_tunnels_per_session	usize	—	接続されたクライアントあたりの最大トンネル数
limits.max_connections_per_tunnel	usize	—	トンネルあたりの最大同時接続数
limits.rate_limit_rps	u32	—	トンネルごとのリクエストレート上限（req/s）
limits.ip_rate_limit_rps	u32	100	送信元 IP ごとのレート上限（req/s）。0 で無効になります
limits.request_body_max_bytes	usize	—	プロキシするリクエスト本文の最大サイズ（バイト）
limits.tcp_port_range	[u16, u16]	—	TCP トンネルポートの範囲（[low, high]、両端を含む）
limits.udp_port_range	[u16, u16]	[0, 0]	UDP トンネルポートの範囲（[low, high]、両端を含む）。[0, 0] で UDP トンネルを無効にします
region.id	string	"default"	トンネル履歴に記録されるリージョン識別子（例："eu"、"us"、"ap"）
region.name	string	"Default"	ダッシュボードに表示される、人が読めるリージョン名
region.location	string	""	物理的な場所を示すラベル（例："Helsinki, FI"）

---

モニタリング

Prometheus メトリクスエンドポイントは :9090/metrics で利用できます：

rustunnel_active_sessions      # gauge: connected clients
rustunnel_active_tunnels_http  # gauge: active HTTP tunnels
rustunnel_active_tunnels_tcp   # gauge: active TCP tunnels

Prometheus と Grafana を含むモニタリングスタック全体を起動します：

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

本番環境での注意： Grafana のデフォルトパスワードは changeme です。本番環境でスタックを起動する前に、GRAFANA_PASSWORD 環境変数を設定してください：

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

---

REST API

ダッシュボードのポートでは、トンネル、トークン、キャプチャしたリクエスト、トンネル履歴にプログラムからアクセスするための REST API を公開しています。ヘルスチェックを除くすべてのエンドポイントで、Authorization: Bearer <token> ヘッダーが必要です。

/api/tunnels、/api/groups と、それぞれのトンネルのサブリソースには、呼び出し元に応じたスコープが適用されます。管理者トークンではすべてが表示され、ユーザースコープの API トークンでは自身のトンネルとグループのみが表示されます。呼び出し元から見えないトンネルに対しては、403 ではなく常に 404 が返されます。詳しいルールについては、docs/api-reference.md § Visibility scope を参照してください。

クイックリファレンス

メソッド	パス	説明
GET	/api/status	ヘルスチェック（認証不要）
GET	/api/tunnels	アクティブなトンネルの一覧
GET	/api/tunnels/:id	単一のトンネルを取得
DELETE	/api/tunnels/:id	トンネルを強制終了
GET	/api/tunnels/:id/requests	キャプチャした HTTP リクエスト
POST	/api/tunnels/:id/replay/:req_id	再生用に保存されたリクエストを取得
GET	/api/tokens	API トークンの一覧
POST	/api/tokens	API トークンを作成
DELETE	/api/tokens/:id	API トークンを削除
GET	/api/history	ページネーション付きトンネル履歴

リクエスト／レスポンスの完全なスキーマ、クエリパラメーター、例については、 docs/api-reference.md を参照してください。

機械可読な OpenAPI 3.0 仕様は GET /api/openapi.json で提供されています（認証不要）。

---

AI エージェントとの連携（MCP サーバー）

rustunnel には、stdio 経由で Model Context Protocol を実装する rustunnel-mcp バイナリが付属しています。 これにより、AI エージェント（Claude、GPT-4o、カスタムエージェント）は手動操作なしでトンネルを開設、管理できます。

あらゆる MCP ハーネスで動作します。 Claude Code、Claude Desktop、Codex、Cursor、Windsurf、Cline、カスタムエージェント向けのコピー＆ペースト可能な設定と、ワンコマンドインストーラーについては、エージェント連携ガイド を参照してください：

./integrations/install.sh        # prompts for your token, writes the config

クイックセットアップ（Claude Desktop — ホスト型サーバー）

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

RUSTUNNEL_TOKEN を一度設定すれば、エージェントはツール呼び出しのたびにトークンを渡す必要がありません。

利用可能なツール

ツール	説明
create_tunnel	トンネルを開設して公開 URL を返します — HTTP／TCP／UDP、P2P、ヘルスチェック付きロードバランシングプールに対応
list_tunnels	アクティブなトンネルをすべて一覧表示
close_tunnel	ID を指定してトンネルを強制終了
list_regions	利用可能なサーバーリージョンを一覧表示
get_connection_info	クラウド／サンドボックスエージェント用の CLI コマンドを返します
get_tunnel_history	過去のトンネルアクティビティを取得

インストール

Homebrew（macOS および Linux） — CLI とともに rustunnel-mcp をインストールします：

brew tap joaoh82/rustunnel
brew install rustunnel

ソースからビルド：

make release-mcp
sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp

セットアップガイド全体、設定オプション、ワークフロー例については、 docs/mcp-server.md を参照してください。

Claude Code プラグイン

Claude Code で rustunnel を使う最も簡単な方法です。 プラグインをインストールすると、すべての MCP 設定が自動的に処理されます。トークンを一度入力するだけで、Claude にポートの公開を依頼できます。

/plugin install rustunnel

プラグインは有効化時にサーバーアドレスと API トークンの入力を求め、安全に保存して、MCP サーバーをバックグラウンドで起動します。.mcp.json の編集や手動設定は不要です。

プラグインディレクトリ： plugins/claude-code/ ドキュメント： docs/claude-plugin.md

OpenClaw スキル

rustunnel には OpenClaw スキルが付属しています。このスキルを使うと、OpenClaw 互換の AI エージェントが rustunnel の設定ファイル形式、認証、ツールのシグネチャ、一般的なワークフローを最初から把握できるため、これらについて説明する必要がありません。

スキルファイル： skills/rustunnel/SKILL.md

対応する内容：

トピック	詳細
設定ファイル	保存場所（~/.rustunnel/config.yml）、形式、名前付きトンネル
初回セットアップ	rustunnel setup ウィザードまたは手動での設定ファイル作成
MCP ツール	create_tunnel、list_tunnels、close_tunnel、get_connection_info、get_tunnel_history
ワークフロー	Webhook のテスト、デモの共有、クラウドサンドボックス（サブプロセスなし）、名前付きトンネル
セキュリティ	トークンの取り扱い、ファイルのアクセス権、HTTPS のみのトランスポート

Claude Code でスキルを読み込むには：

/skills load skills/rustunnel/SKILL.md

読み込み後は、エージェントに次のように依頼できます。

「rustunnel を使って、ローカルポート 3000 を HTTPS トンネルとして公開してください。」

「アクティブなトンネルを一覧表示して、ポート 5432 に転送しているトンネルを閉じてください。」

「トークンを使って rustunnel の設定ファイルをセットアップしてください。」

このスキルは、エージェントが ~/.rustunnel/config.yml から認証情報を自動的に読み取るよう指示するため、呼び出すたびにトークンの入力を求められることはありません。

---

ロードマップ

リリース済みの機能と今後予定されている作業の詳細な一覧は、docs/ROADMAP.md で管理されています。

---

コントリビューション

コントリビューションを歓迎します！次の手順に従ってください。

1. リポジトリを フォーク し、main からフィーチャーブランチを作成します。
2. クローン後に一度 make install-hooks を実行して、プッシュ前の品質チェックを有効にします。
3. 変更を加えます。make check（fmt + Clippy）と make test がローカルで成功することを確認してください。
4. 変更内容とその理由を明記した プルリクエスト を作成します。
5. CI が成功したら、メンテナーがレビューしてマージします。

ガイドライン

• PR は目的を絞り、1 つの PR につき論理的な変更を 1 つにしてください。
• 新しい動作を追加する場合は、テストを追加または更新してください。
• 既存のコードスタイルに従ってください。cargo fmt は CI で適用されます。
• 大規模な変更や新機能については、まずイシューを作成して進め方を相談してください。

---

ライセンス

このプロジェクトは GNU AGPLv3 License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

---

お問い合わせ

João Henrique Machado Silva

• GitHub：@joaoh82
• プロジェクト：github.com/joaoh82/rustunnel
• イシューと機能リクエスト：GitHub Issues