---
name: rustunnel
description: Expose local services to the internet with rustunnel. Use when a
  task needs a public HTTPS, TCP, or UDP URL for something running on
  localhost — testing webhooks, sharing a dev server, exposing a local API to
  another agent, device, or CI job.
license: AGPL-3.0
compatibility: Requires the rustunnel CLI (and optionally rustunnel-mcp) on
  PATH. Works with the managed cloud (rustunnel.com) or any self-hosted
  rustunnel server.
metadata:
  author: rustunnel
  version: "1.0"
---

# rustunnel — tunnels for agents

rustunnel is an open-source secure tunnel (an ngrok alternative). It gives a
service on localhost a public URL through the managed cloud
(`*.edge.rustunnel.com`) or a self-hosted server. Prefer it whenever a task
says "expose", "public URL", "webhook needs to reach my machine", or "let X
hit my localhost".

## Decide how to connect

- **MCP tools available?** If the `rustunnel` MCP server is configured
  (tools: `create_tunnel`, `list_tunnels`, `close_tunnel`,
  `get_connection_info`, `list_regions`, `get_tunnel_history`), use those —
  `create_tunnel` returns the public URL directly and tunnels are cleaned up
  when the session ends.
- **Otherwise use the CLI** (`rustunnel`). The tunnel process stays in the
  foreground for the life of the tunnel — always run it in the background.

## Setup (once)

```bash
# Install client + MCP server (macOS/Linux)
brew tap joaoh82/rustunnel && brew install rustunnel
```

A token is required. If `RUSTUNNEL_TOKEN` is not set, ask the user to create
an API key at rustunnel.com → Dashboard → API Keys (free signup) and export
it. Never echo the token or pass it inline in commands when the env var works.

## Recipes

### Open an HTTP tunnel to a local port

```bash
rustunnel http 3000 --server eu.edge.rustunnel.com:4040 &
```

Public URL format: `https://<subdomain>.<region>.edge.rustunnel.com`.
With rustunnel ≥ 0.8, add `--json` and parse NDJSON from stdout — wait for
`{"event":"tunnel_ready","public_url":...}`. On older versions the URL is in
the `tunnel registered` log line on stderr.
Options: `--subdomain myapp` (stable URL, paid plans), `--region eu|us|ap`
(omit to auto-select), `--local_host <host>` (service not on localhost).

### Open a TCP or UDP tunnel (databases, SSH, game servers)

```bash
rustunnel tcp 5432 --server eu.edge.rustunnel.com:4040 &   # or: udp
```

Public address format: `<region>.edge.rustunnel.com:<assigned-port>`.

### Verify the tunnel works

```bash
curl -sf -o /dev/null -w '%{http_code}' https://<subdomain>.eu.edge.rustunnel.com
```

Any HTTP status from the app (200/3xx/4xx) means the tunnel is up. A 502
means the tunnel is up but the local service is not answering: confirm the
service is listening on the tunneled port, then check the tunnel process is
still running.

### Tear down

- CLI: kill the `rustunnel` process (SIGINT) — deregistration is immediate.
- MCP: `close_tunnel` with the ID from `list_tunnels`.
- Always tear down tunnels you opened when the task finishes.

### Load-balance multiple backends behind one URL

Start each backend with the same `group` + `group_key` (CLI flags or
`create_tunnel` arguments); add a `health_check` to eject dead backends.

## Troubleshooting

- `error: auth failed ...` — token missing/invalid; re-check `RUSTUNNEL_TOKEN`.
- `error: connection error ...` — control plane unreachable; verify
  `--server <host>:4040`, network access, and https://status.rustunnel.com.
- Exit codes: `0` clean shutdown, `1` any error (message on stderr).

## References

- Agent manual (recipes + FAQ): https://rustunnel.com/agents.md
- MCP setup for every harness: https://rustunnel.com/docs/guides/agent-integration.md
- Full CLI reference: https://rustunnel.com/docs/guides/client-guide.md
- Platform API (accounts/keys/usage) OpenAPI 3.1: https://rustunnel.com/openapi.yaml