Hosted, multi-user network relay at https://relaynet.network (relay endpoint
wss://relay.relaynet.network). Clients with their own TCP/IP stack (browser
VMs, or user-space stacks for SSH, USB/IP, debug and custom protocols) send
Ethernet frames over a WebSocket and get IPv4 TCP and UDP to the internet;
sessions of one account share a private network. The docs page
(web/docs/docs.md) lists use cases and when to use something else.
Run your own
git clone https://github.com/beriberikix/relaynet cd relaynet && docker compose up
Then open http://localhost and create an account (or sign in as admin with
the password printed once in docker compose logs relay); the operator panel
is on http://127.0.0.1:8001. No configuration or third-party accounts are
needed. compose.yaml lists the optional settings: a domain for HTTPS,
single sign-on with any OpenID Connect provider, S3 backups. The guides are
in docs/self-hosting/: quick start, single server,
single sign-on, and how relaynet.network itself is deployed.
This repository and rootlessRelay
relaynet is three layers in two places:
- Upstream engine: obegron/rootlessRelay (MIT), a user-space TCP/IP relay for browser VMs.
- The fork: beriberikix/rootlessRelay (MIT). It adds hosted mode: accounts, orgs, tokens, tiers, quotas, metering, the audit log, OIDC and the operator panel. All relay code is here, and so are its tests and releases. Fixes to the engine go upstream where they apply (upstream merged its TCP slow start from the fork), and the fork pulls upstream releases. Hosted mode stays in the fork.
- This repository (Apache-2.0). It pins a fork release tarball in
relay/package.jsonand holds everything around it: the site and dashboard, the client library, the container images, compose self-hosting, deployment and operations tooling, and docs.
Send relay behaviour changes to the fork and everything else here
(CONTRIBUTING.md). Issues for work that lands in the fork are tracked in
this repository with the repo:fork label.
compose.yaml quick start: the relay and the site on one machine
deploy/ the site's container (Caddy) for compose and other hosts
relay/ container image + Fly.io config for the relay process
web/ browser frontend (Cloudflare Worker, static assets)
client/ relaynet.js, the reconnecting client helper (npm: relaynet)
infra/ operator tooling (probes, load test, Grafana, legal pages) and setup
notes for Cloudflare, Auth0 and operator access
docs/ self-hosting guides, design notes, security audit and threat model
Bump the relay by changing the tarball version in relay/package.json and
running npm install there to refresh the lockfile.
Pushes to main that change either image publish them to GitHub's container
registry, with build-provenance attestations (publish-images.yml):
ghcr.io/beriberikix/relaynet-relay (tagged with the rootlessRelay version)
and ghcr.io/beriberikix/relaynet-web.
System Overview
Three deployable pieces sit around the pinned relay. Self-hosted, they run on one origin. On relaynet.network, they are split across Cloudflare and Fly.io.
- Relay (
relay/): therootlessrelayprocess in a container. It serves therelay.v1WebSocket (Ethernet frames), the/api/*account routes and/healthzon port 8086, and/metrics(plus the operator panel in compose) on port 8001. Its SQLite database is at/data/relay.sqliteand is replicated with Litestream whenLITESTREAM_BUCKETis set. - Site (
web/, plusdeploy/caddy/for self-hosting): static landing page and account dashboard.web/public/app.jscalls the relay's/api/*routes with a Bearer token from a relay sign-in or an OIDC provider.config.js(window.RELAYNET_CONFIG) tells it where the relay is. The Caddy image serves the same files and reverse-proxies/api/*,/healthzand WebSocket upgrades to the relay. - Clients (
client/):relaynet.js, a reconnecting WebSocket transport that speaksrelay.v1and passes the token as therelay.token.<token>subprotocol.
infra/ holds operator tooling that drives those pieces from outside:
probes, a load generator, Grafana provisioning, and the legal-page generator.
Subdirectories & System Boundaries
- client:
./client/README.md-relaynetnpm package (MIT):connectRelay/RelayConnection, a reconnectingrelay.v1transport with heartbeat, backoff and close classification. - deploy:
./deploy/README.md- Docker compose self-hosting assets: therelaynet-webCaddy image (./deploy/caddy/README.md) andcompose-check.sh, the end-to-end smoke test for the compose quick start. - infra:
./infra/README.md- operator tooling: Grafana alerts and dashboard, legal-page build, load generator, CLI probe and its Cloudflare Worker version, staging operator script, Fly log shipper config. - relay:
./relay/README.md- relay container image, Litestream backups, Fly.io production and staging configs. It has no relay code of its own. - web:
./web/README.md- relaynet.network Cloudflare Worker (static assets) and dashboardapp.js; docs source and generator in./web/docs/README.md. docs/: design notes, security audit and threat model, and the self-hosting guides. Prose only, so it has no contract.
Global Invariants
- The relay is a pinned dependency (
relay/package.json). This repository changes it only by bumping the version, never by patching it. - One relay machine per deployment: sessions and the IP pool are in memory
(
relay/fly.toml,fly deploy --ha=false). - Tokens travel only as the
relay.token.<token>WebSocket subprotocol or asAuthorization: Beareron/api/*.client/relaynet.jsrefuses to send a token overws://to a non-loopback host. - The site's non-CSP security headers are duplicated by hand in
web/public/_headers(Cloudflare) anddeploy/caddy/Caddyfile. The Caddy CSP is generated from the environment bydeploy/caddy/entrypoint.sh, and it differs from_headerson purpose. - Files in
web/public/generated from Markdown (docs.html,docs.md,llms.txt,terms.html,acceptable-use.html,privacy.html) are never edited by hand. Editweb/docs/docs.mdorinfra/legal/*.mdand rebuild. infra/probe/probe.mjsandinfra/probe-worker/src/index.tsrun the same end-to-end check (connect, DHCP, DNS) and must stay in step.- Base images and downloaded binaries are pinned by digest or checksum
(
relay/Dockerfile,deploy/caddy/Dockerfile,infra/log-shipper/fly.toml).
Global Side Effects
- Relay SQLite database on the
/datavolume, replicated to S3-compatible storage (Cloudflare R2 on relaynet.network) when Litestream is enabled. - Outbound internet egress (IPv4 TCP/UDP) on behalf of relay sessions. The probes and load generator cause real DNS and HTTP egress through it.
- Deploys from GitHub Actions: Fly.io (relay, staging first; log shipper),
Cloudflare Workers (site, probe worker), npm (
client/), GHCR (relaynet-relayandrelaynet-webimages).relay-rollback.ymlredeploys an earlier relay image by hand; schema migrations are not undone. - Production data read by GitHub Actions:
backup-restore-check.yml(weekly) andmigration-rehearsal.yml(by hand) restore the production replica from R2 with a read-only key onto the runner. Neither writes back; a failed weekly check opens an issue. - Monitoring: Grafana Cloud alerts and dashboard (
infra/grafana/provision.py), Better Stack heartbeat from the probe worker and from manualrelay-probe.ymlruns. - Browser storage on the site:
localStorage(selected org, OIDC user store) andsessionStorage(relay session, pending invite).
System Verification
There is no root build. Run what CI runs (.github/workflows/ci.yml), from
the repository root:
(cd client && npm test) for f in web/public/*.js; do node --check "$f"; done python3 web/docs/build.py && git diff --exit-code -- web/public docker compose up -d --build --wait --wait-timeout 180 && deploy/compose-check.sh docker compose down -v # deletes the stack's volumes, including the relay database
The relay-image job's build and /healthz smoke test is in
./relay/README.md.
License
Apache-2.0 (see LICENSE), except client/, which is MIT (client/LICENSE).
The relay, rootlessRelay, is
MIT. The names "relaynet" and "relaynet.network" are not licensed; see
TRADEMARKS.md for how to use them, GOVERNANCE.md for how the project is
run, and docs/design/license-options.md for why the licensing is set up
this way. Contributions are signed off under the DCO (CONTRIBUTING.md).