# rtun — a development proxy for temporary services

You fetched this from an **rtun server**. rtun is a development proxy:
it takes a service running on your own machine — a dev server, a staging
build, a webhook receiver, a demo — and exposes it on a public internet
endpoint for as long as you need it. When your client disconnects, the
endpoint closes. Nothing is hosted here permanently; the server only
relays traffic between visitors and connected clients.

Technically it is a small encrypted WebSocket reverse tunnel (one binary
is both server and client). rtun clients connect to the same host:port
serving this page, with a WebSocket upgrade carrying `Sec-Is-Rtun: YES`;
everything else (browsers, curl, you) gets this static site.

## Typical use

```sh
# you have something on localhost:3000 — a dev server, an API, a demo
# expose it on this proxy's public endpoint:
RTUN_PASSWORD='...' rtun client \
  --server ws://51.81.245.144:5918 \
  --host-key SHA256:qcDVJNP5j0j/B8NQPhM20VdQja+hJ27hJCDYnrXG/G8 \
  --target 127.0.0.1:3000 --remote-port 9001 --proto tcp
# share the "public endpoint" URL from the client log with whoever
# needs to see it; stop the client when you're done and it's gone
```

Use it for: previewing work-in-progress, testing webhooks and callbacks
against a real public URL, sharing a build with a teammate, reaching a
service on a machine that sits behind NAT. Don't use it as permanent
hosting — endpoints last exactly as long as their client stays connected.

## This site

| Path         | What it is                                             |
|--------------|--------------------------------------------------------|
| `/`          | This file (AGENTS.md)                                  |
| `/AGENTS.md` | This file, by name                                     |
| `/rtun.tar.gz` | Tarball containing the `rtun` binary (Linux x86_64, static musl build — runs on glibc and musl) |
| `/rtun-src.tar.gz` | Full source tarball of this rtun build (Rust crate: server + client, including the egress/TUN/static-site/UDP patches) |
| `/setup.sh`  | Installer script: downloads and installs the binary    |

## Install

```sh
curl -fsSL http://51.81.245.144:5918/setup.sh | sh
# or manually:
curl -fsSL http://51.81.245.144:5918/rtun.tar.gz | tar -xz
install -m 755 rtun ~/.local/bin/rtun
```

`setup.sh` honors `RTUN_BASE` (where to download from, default this server)
and `RTUN_INSTALL_DIR` (default `~/.local/bin`).

## Expose a service

You need the **tunnel password from the server's owner** — it is never
served from this site. Supply it via the `RTUN_PASSWORD` environment
variable or `--password`. Pin the server host key instead of trusting on
first use when the owner gives you one (this server:
`SHA256:qcDVJNP5j0j/B8NQPhM20VdQja+hJ27hJCDYnrXG/G8`).

The client entry point is the same host:port you fetched this file from,
with the scheme swapped to `ws://` (or `wss://` if the server terminates
TLS) — see the example above. While the client runs, it auto-reconnects
with backoff if the connection drops; run it under setsid/nohup/systemd
for anything longer than a quick test.

On this server the claimable internal ports are **9000-9003**, published
externally as **6195, 6623, 6772, 6773** respectively (9000 is the
owner's own SSH endpoint — pick another). `--remote-port 0` lets the
server pick a port. The server reports the mapping back: when your
tunnel opens, the client logs a
`public endpoint: 51.81.245.144:<external-port>` line — that, not the
internal port in the `tunnel live` line, is the address visitors use.

## Also available

- **Egress passthrough** (the reverse direction — exit your traffic via
  the server; enabled here): add `--proxy-listen 127.0.0.1:1080` to the
  client (no `--target` needed), then use it as an HTTP/SOCKS5 proxy,
  e.g. `curl --noproxy '' -x http://127.0.0.1:1080 https://example.com/`.
- **TUN**: `--tun rtun0 --tun-addr 10.99.0.2/24` on the client pipes raw
  IP packets to the server (needs root/CAP_NET_ADMIN on both ends).

## Etiquette

- Endpoints are temporary: claim a port only while you're actively
  exposing something, and release it when you're done.
- TCP and UDP both work: use `--proto tcp`, `--proto udp`, or
  `--proto both`. UDP is datagram forwarding — one visitor address is
  one flow, flows expire after 60 s idle, datagram boundaries are
  preserved.
- Do not guess the password or brute-force the handshake; ask the owner.