> ## Documentation Index
> Fetch the complete documentation index at: https://rustunnel.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# rustunnel Quickstart — expose localhost in three steps

> 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 cols={2}>
  <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>