swsrs

Tiny by design

A static Go binary, about 7 MB on linux/arm64. Designed to run happily on a $3/month t4g.nano. Multi-stage distroless Docker image too.

Two-plane auth

Admin API gated by OIDC + scopes. Data plane gated by opaque per-slot tokens minted at session creation. Connecting peers never need an IdP identity — the canonical pattern for support-engineer-to-customer-machine tunnels.

Protocol-agnostic relay

Forwards opaque WebSocket binary frames. TCP, UDP, gRPC, SSH, raw bytes — all handled client-side via SDK or CLI adapters. The server stays auditable and unchanged when you add new protocols.

Embed it directly

Go SDK returns a net.Conn that drops into grpc.WithContextDialer, http.Transport, crypto/tls. TypeScript SDK works in browser and Node 22+, zero runtime deps. Your app IS the peer — no CLI on the user's machine.

Zero IdP coordinates on clients

/.well-known/swsrs-config publishes the IdP endpoints so swsrs auth runs OAuth 2.0 device flow without anyone configuring issuer URLs, client IDs, or scopes manually.

Ready to deploy

Multi-arch (amd64 + arm64) Docker image at ghcr.io. GoReleaser cross-builds for Linux, macOS, Windows. npm Trusted Publishing (OIDC, no NPM_TOKEN). Single git tag releases everything.

What it's for

You have a service behind NAT — a diagnostic probe, a dev server, a customer's machine — and you need to reach it from somewhere else without poking holes in firewalls or running a VPN. swsrs is one rendezvous endpoint that both sides open an outbound WebSocket to. No port forwarding, no inbound rules, no client-side daemons in your customers' networks.

What makes it different

Most NAT-traversal tools either (a) skip auth or use a shared secret, or (b) bundle a heavyweight gateway you can't fit on a t4g.nano. swsrs sits in the gap:

The party who can mint sessions is gated by your IdP (OIDC, scope-claim).

The parties who actually use the tunnel are gated by short-lived per-slot tokens — they need no IdP identity.

The server never inspects payloads — it forwards opaque frames. Your app decides the protocol.

Try it

bash

# Run the relay locally with auth disabled (dev only)
go run github.com/emdzej/swsrs/cmd/swsrs@latest serve --no-auth --addr :8080

# In another terminal — end-to-end chat over the relay
bash scripts/smoke-chat.sh
# [smoke] PASS

For production: pick an IdP, point --oidc-issuer at it, and your clients run swsrs auth once. Step-by-step setup for Keycloak / Auth0 →

swsrsSimple WebSocket Relay Service