Unstuck Docs GitHub

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

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:latest

Pin 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.mjs

relay-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 deploy

Your 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-1

That'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 --open

UNSTUCK_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

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.