rustunnel

# Rustunnel - Secure Tunnel Management Expose local services (HTTP/TCP) through public URLs using rustunnel. Perfect for testing webhooks, sharing local development, and deployment workflows. ## When to Use - **Webhook testing** - Expose local server to receive webhooks from external services - **Demo sharing** - Share local development with stakeholders - **CI/CD integration** - Expose preview environments - **Database access** - Expose local TCP services (PostgreSQL, Redis, etc.) - **Mobile testing** - Test mobile apps against local backend ## ⚠️ IMPORTANT: Use MCP Tools, Not CLI **Always use MCP tools for tunnel management.** They handle lifecycle automatically. | Method | Lifecycle | Recommended | |--------|-----------|-------------| | **MCP tools** (create_tunnel, close_tunnel) | Automatic cleanup | ✅ Yes | | **CLI** (rustunnel http 3000) | Manual process management | ❌ Only for cloud sandboxes | **Why MCP tools?** - Automatic cleanup when closed - No orphaned processes - Proper tunnel lifecycle management - Returns tunnel_id for tracking --- ## Configuration File **Location:** `~/.rustunnel/config.yml` This file stores your server address and auth token. The agent will read from this file instead of asking every time. **Format:** ```yaml # rustunnel configuration # Documentation: https://github.com/joaoh82/rustunnel server: edge.rustunnel.com:4040 auth_token: your-token-here tunnels: expense_tracker: proto: http local_port: 3000 # api: # proto: http # local_port: 8080 # subdomain: myapi ``` ## First-Time Setup **Before using tunnels, ensure config exists:** 1. **Check if config file exists:** `~/.rustunnel/config.yml` 2. **If not, ask user:** "What's your rustunnel auth token and server address?" 3. **Create config file directly:** ```bash mkdir -p ~/.rustunnel chmod 700 ~/.rustunnel ``` 4. **Write config with user's token:** ```yaml server: <user-provided-server> auth_token: <user-provided-token> ``` 5. **Set permissions:** `chmod 600 ~/.rustunnel/config.yml` --- ## Agent Workflow **Always follow this sequence:** ### Step 1: Check Config ```bash # Check if config exists cat ~/.rustunnel/config.yml ``` **If config exists with auth_token:** Read token and proceed. **If config missing:** 1. Ask user: "What's your rustunnel auth token and server address?" 2. Create config file directly: ```bash mkdir -p ~/.rustunnel chmod 700 ~/.rustunnel ``` 3. Write config with user's token: ```yaml server: <user-provided-server> auth_token: <user-provided-token> ``` 4. Set permissions: `chmod 600 ~/.rustunnel/config.yml` ### Step 2: Read Token from Config When making tool calls, read `auth_token` from `~/.rustunnel/config.yml`: ```yaml auth_token: your-token-here server: edge.rustunnel.com:4040 ``` Use these values in tool calls - **don't ask the user every time.** ### Step 3: Use MCP Tools With token from config, call MCP tools directly. --- ## MCP Tools (Recommended) ### create_tunnel Expose a local port and get a public URL. **Parameters:** | Param | Type | Required | Description | |-------|------|----------|-------------| | `token` | string | yes | API token (read from config) | | `local_port` | integer | yes | Local port to expose | | `protocol` | "http" \| "tcp" | yes | Tunnel type | | `subdomain` | string | no | Custom subdomain (HTTP only) | | `region` | string | no | Region ID (e.g. `"eu"`, `"us"`, `"ap"`). Omit to auto-select. Use `list_regions` to see options. | **Returns:** ```json { "public_url": "https://abc123.edge.rustunnel.com", "tunnel_id": "a1b2c3d4-...", "protocol": "http" } ``` **Lifecycle:** Tunnel stays open until `close_tunnel` is called or MCP server exits. ### close_tunnel Close a tunnel by ID. Public URL stops working immediately. **Parameters:** | Param | Type | Required | Description | |-------|------|----------|-------------| | `token` | string | yes | API token | | `tunnel_id` | string | yes | UUID from create_tunnel | **This is the proper way to close tunnels.** No orphaned processes. ### list_tunnels List all currently active tunnels. **Parameters:** | Param | Type | Required | Description | |-------|------|----------|-------------| | `token` | string | yes | API token (read from config) | **Returns:** JSON array of tunnel objects. ### get_tunnel_history Retrieve history of past tunnels. **Parameters:** | Param | Type | Required | Description | |-------|------|----------|-------------| | `token` | string | yes | API token | | `protocol` | "http" \| "tcp" | no | Filter by protocol | | `limit` | integer | no | Max entries (default: 25) | ### list_regions List available tunnel server regions. No authentication required. **Parameters:** None **Returns:** JSON array of region objects: ```json [ { "id": "eu", "name": "Europe", "location": "Helsinki, FI", "host": "eu.edge.rustunnel.com", "control_port": 4040, "active": true } ] ``` ### get_connection_info Returns the CLI command string without spawning anything. Use when MCP can't spawn subprocesses (cloud sandboxes, containers) or you prefer running the CLI yourself. **Parameters:** | Param | Type | Required | Description | |-------|------|----------|-------------| | `token` | string | yes | API token | | `local_port` | integer | yes | Local port to expose | | `protocol` | "http" \| "tcp" | yes | Tunnel type | | `region` | string | no | Region ID (e.g. `"eu"`). Omit to auto-select. | **Returns:** ```json { "cli_command": "rustunnel http 3000 --server edge.rustunnel.com:4040 --token abc123", "server": "edge.rustunnel.com:4040", "install_url": "https://github.com/joaoh82/rustunnel/releases/latest" } ``` --- ## Common Workflows --- ## Common Workflows ### 1. Expose Local API (MCP Tools) ``` 1. Read auth_token from ~/.rustunnel/config.yml 2. Create tunnel: create_tunnel(token, local_port=3000, protocol="http") 3. Store tunnel_id for later cleanup 4. Return public_url to user 5. When done: close_tunnel(token, tunnel_id) ``` ### 2. Custom Subdomain ``` 1. Read auth_token from config 2. create_tunnel(token, local_port=5173, protocol="http", subdomain="myapp-preview") 3. Return URL: https://myapp-preview.edge.rustunnel.com 4. close_tunnel(token, tunnel_id) when done ``` ### 3. TCP Tunnel (Database) ``` 1. Read auth_token from config 2. create_tunnel(token, local_port=5432, protocol="tcp") 3. Return tcp://host:port for connection 4. close_tunnel(token, tunnel_id) when done ``` ### 4. Cloud Sandbox (CLI Fallback) ``` 1. Read auth_token from config 2. get_connection_info(token, local_port=3000, protocol="http") 3. Output CLI command for user to run locally 4. User runs command 5. list_tunnels(token) to verify and get public_url 6. When done, user Ctrl+C the CLI process ``` --- ## Prerequisites 1. **Rustunnel MCP server installed:** ```bash # 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-mcp sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp ``` 2. **Config file:** `~/.rustunnel/config.yml` with `auth_token` set ## MCP Configuration Add to your MCP client config: ```json { "mcpServers": { "rustunnel": { "command": "rustunnel-mcp", "args": [ "--server", "edge.rustunnel.com:4040", "--api", "https://edge.rustunnel.com:8443" ] } } } ``` **Note:** The MCP server address should match the `server` in `~/.rustunnel/config.yml`. --- ## Architecture ``` Internet ──── :443 ────▶ rustunnel-server ────▶ WebSocket ────▶ rustunnel-client ────▶ localhost:PORT │ Dashboard (:8443) REST API ``` ## Security Notes - Tokens are sent over HTTPS (use `--insecure` only in local dev) - MCP tools handle process cleanup automatically - Tunnels are closed when MCP server exits - Config file should be protected: `chmod 600 ~/.rustunnel/config.yml` --- ## Related Skills - **vercel-deploy** - Deploy to Vercel for production hosting - **here-now** - Instant static file hosting - **backend** - Backend service patterns - **nodejs-patterns** - Node.js deployment patterns ## Resources - [GitHub Repository](https://github.com/joaoh82/rustunnel) - [MCP Server Documentation](https://github.com/joaoh82/rustunnel/blob/main/docs/mcp-server.md) - [API Reference](https://github.com/joaoh82/rustunnel/blob/main/docs/api-reference.md)