Documentation
Getting started
Install the relay CLI, authenticate with your token, and
expose a local port to the internet. Most flows take under a minute.
Install
Choose the path that matches your setup. Homebrew is the quickest on macOS.
One-liner — taps the repo and installs the formula:
brew tap afomera/relay https://github.com/afomera/relay.git && brew install relayVerify the install:
relay --versionIf you have a Rust toolchain, install directly from the repo. Works on Intel macOS, Linux, and Windows:
cargo install --git https://github.com/afomera/relay relay-cli
Make sure ~/.cargo/bin is on your PATH.
Prefer a one-liner? The install script grabs the right binary for your OS:
curl -fsSL https://raw.githubusercontent.com/afomera/relay/main/scripts/install.sh | shAuthenticate
Run relay auth login and relay opens your browser to
the dashboard, where you sign in and authorize the CLI. Once you approve, relay saves the
token locally so relay http and friends just work.
relay auth login
The token is written to config.toml in relay's config
directory — ~/Library/Application Support/dev.withrelay.relay/
on macOS, ~/.config/relay/ on Linux, and the equivalent
%APPDATA% path on Windows. You only need to do this once
per machine.
On a headless box? Pass --no-browser to print the
sign-in URL, or skip the handshake with
relay auth login --token rly_pat_… or the
RELAY_AUTH_TOKEN environment variable.
Start a tunnel
Once authenticated, point relay at any local port. Four common shapes:
HTTP on a generated hostname
The fastest path. Relay picks a memorable subdomain on the shared zone:
relay http 3000
# → https://bright-otter.temporary.sharedwithrelay.comReserved wildcard hostname
Claim a stable name under your account's wildcard. Great for demos and webhooks:
relay http 3000 --hostname api.andrea
# → https://api.andrea.sharedwithrelay.comCustom domain
Bring your own domain. Point a CNAME at relay, and certificates are provisioned automatically:
relay http 3000 --domain tunnel.mycompany.comRaw TCP
For Postgres, Redis, SSH, or anything else that speaks TCP:
relay tcp 5432
# → tcp.sharedwithrelay.com:29734What's next
-
Explore the full CLI with
relay --help. - Want to run your own control plane? See the self-hosting guide.
- Read the spec for architecture and milestones.