Self-host the relay
Unstuck is open source, and the relay that connects your agent to a person's phone is too. Run it on your own server and takeover links open on any phone, with no Unstuck account and no data passing through unstuck.sh.
The relay is small: agents and phones both connect out to it, it pairs them, and it forwards bytes it can't read (the screen, taps and typing are encrypted end to end between your agent's engine and the person's browser). It keeps nothing on disk.
Self-hosted or Unstuck Cloud
| Self-hosted relay | Unstuck Cloud | |
|---|---|---|
| Price | Free (your server costs) | 100 takeovers a month free, then from 1.6¢ each |
| Links open on | any phone, through your relay | any phone, through relay.unstuck.sh |
| Setup | run the relay, put it behind HTTPS, share keys | one API key |
| End-to-end encryption, page lock, single-use links | yes | yes |
| Phone alerts (notification, Telegram, email) | no | yes |
| Dashboard, API keys, usage | no (keys in an environment variable) | yes |
| Viewer page | served by your relay | served from its own origin with published checksums |
| Who runs it | you | Unstuck |
Choose self-hosting when links must stay on your infrastructure or you'd rather run it yourself. Choose Unstuck Cloud when you'd rather not run a server, or want phone alerts and a dashboard.
Before you start
- HTTPS is required. The viewer decrypts the screen with the browser's Web Crypto API, which phones only allow on
https://pages (or onlocalhost). Put the relay behind a TLS reverse proxy, or use Cloudflare Workers, which serves HTTPS for you. - Pick strong agent keys. Every agent connects with a key from your list; generate each one with
openssl rand -hex 24. - Keep the relay up to date. The relay serves the viewer page, so rebuild it when you upgrade the SDK.
Option 1: Docker
Run the published image with your keys. It's built from the open-source repository for linux/amd64 and linux/arm64:
docker run -d --name unstuck-relay --restart unless-stopped \
-p 127.0.0.1:8787:8787 \
-e UNSTUCK_AGENT_KEYS="key-for-agent-1,key-for-agent-2" \
-e UNSTUCK_TRUST_PROXY=1 -e UNSTUCK_HSTS=1 \
ghcr.io/velmlabs/unstuck-relay:latestPin a version (ghcr.io/velmlabs/unstuck-relay:0.2.0) to upgrade on your own schedule. Each image carries signed build provenance from GitHub Actions; check it with gh attestation verify oci://ghcr.io/velmlabs/unstuck-relay:latest --owner velmlabs. To build the image yourself instead: git clone https://github.com/velmlabs/unstuck.git && cd unstuck && docker build -f relay-node/Dockerfile -t unstuck-relay .
Then put HTTPS in front of it. With Caddy, which gets the certificate for you and passes WebSockets through, the whole config is:
relay.example.com {
reverse_proxy 127.0.0.1:8787
}Check it: curl https://relay.example.com/healthz answers {"ok":true}.
Option 2: Node, without Docker
Node.js 22 or later and pnpm:
git clone https://github.com/velmlabs/unstuck.git
cd unstuck
pnpm install
pnpm --filter @velmlabs/unstuck-viewer build
pnpm --filter @velmlabs/unstuck-relay bundle
UNSTUCK_AGENT_KEYS="key-for-agent-1" UNSTUCK_VIEWER_DIR=viewer/dist node relay-node/dist/relay.mjsrelay-node/dist/relay.mjs is the whole relay in one file; copy it with viewer/dist to any server. Run it under systemd or another process manager, behind the same HTTPS proxy as above.
Option 3: Cloudflare Workers
The relay also runs on Workers, with one Durable Object per takeover. You need a Cloudflare account and Wrangler:
git clone https://github.com/velmlabs/unstuck.git
cd unstuck
pnpm install
cd relay-cloudflare
npx wrangler secret put AGENT_KEYS # comma-separated keys
pnpm deployYour relay is at https://unstuck-relay-selfhost.<your-subdomain>.workers.dev (rename it in relay-cloudflare/wrangler.toml). HTTPS and rate limits are already set up.
An agent that runs as a Worker, on the same account or another, uses it the same way: new Unstuck({ relay: 'wss://unstuck-relay-selfhost.<your-subdomain>.workers.dev', agentKey }). See Cloudflare Workers.
Point your agents at it
Set two variables where the agent runs. Use wss:// and your relay's host:
export UNSTUCK_RELAY_URL=wss://relay.example.com
export UNSTUCK_AGENT_KEY=key-for-agent-1That's all the SDKs need: takeover() now registers with your relay, and links look like https://relay.example.com/s/…. For the MCP server, pass the same variables:
claude mcp add unstuck -e UNSTUCK_RELAY_URL=wss://relay.example.com -e UNSTUCK_AGENT_KEY=key-for-agent-1 \
-e UNSTUCK_CDP_URL=http://127.0.0.1:9222 -- npx -y @velmlabs/unstuck-engine --mcp --openUNSTUCK_RELAY_URL wins over UNSTUCK_API_KEY, so an agent can't fall back to Unstuck Cloud by accident. A wrong key ends the takeover with status failed and detail relay_unauthorized.
Settings
| Variable | Relay | Meaning |
|---|---|---|
UNSTUCK_AGENT_KEYS |
Node, Docker | Comma-separated keys allowed to start takeovers |
AGENT_KEYS |
Workers (secret) | The same, as a Worker secret |
PORT, --port, --host |
Node, Docker | Where to listen (default 0.0.0.0:8787) |
UNSTUCK_TRUST_PROXY=1 |
Node, Docker | Read client IPs from X-Forwarded-For (behind your own proxy only; the value is how many proxies you trust) |
UNSTUCK_HSTS=1 |
Node, Docker | Send Strict-Transport-Security (when clients only reach it over HTTPS) |
UNSTUCK_RELAY_OPEN=1 |
Node, Docker | Accept any agent without a key. Local testing only |
What the relay does and keeps
- Pairs one agent with one person per takeover and forwards encrypted bytes; it can't read the screen, taps or typing.
- Keeps each takeover in memory for at most its expiry (1 hour at most) plus a minute, then drops it. Nothing is written to disk.
- Prints usage events (
session_opened,takeover_opened,session_closed) as JSON lines on stderr, for your own logs or billing. - Rate-limits connections and closes slow or unconfirmed viewers, so a leaked link or a busy phone can't stall your agent.
License
The relay (relay-core, relay-node, relay-cloudflare) is AGPL-3.0: use and modify it freely, and if you offer a modified relay to others as a service, share your changes. The SDKs, engine and viewer are Apache-2.0.