Use your own server and domain.

Before you start

You need Docker with Compose, a domain pointing at the server, and ports 80/443 reachable for HTTPS. The standalone relay is single-node. It is not the optional accounts app or the native Worker MCP implementation.

1. Get the standalone deployment

Use the standalone directory, not the root Compose file. The root file starts a terminal client; this one runs a relay.

git clone https://github.com/TeoSlayer/shell.online.git
cd shell.online/standalone

Copy

Prepare the relay on your server.

2. Set your public domain

Replace the example domain with your own. Caddy obtains HTTPS certificates when DNS and ports are ready.

SHELL_ONLINE_PUBLIC_URL=https://relay.example.com SHELL_ONLINE_SITE=relay.example.com docker compose up -d --build

Copy

Start the relay and HTTPS proxy.

3. Start a session through it

On the computer doing the work, select your relay. Keep HTTPS for a real deployment.

shell --server https://relay.example.com claude

Copy

The generated link points at your server.

Try it locally first

For a loopback-only trial, the default Compose settings use HTTP localhost. This is not a public deployment configuration.

docker compose up -d --build

Copy

Run from the standalone directory.

curl http://localhost/api/health

Copy

Check the local relay response.

Protect state and keep one replica

The relay-state volume contains session metadata and host-token hashes, not browser passwords or E2EE frame keys. Back it up. Do not run multiple relay replicas against the same state file.

Live sockets reconnect after a restart. The standalone relay stores metadata, not a terminal transcript. Default E2EE still happens between the host and browser.

Configuration reference

Trust forwarded addresses only when the relay is behind your own trusted proxy.

SHELL_ONLINE_PUBLIC_URL

Exact public origin used in links and browser-origin checks.

SHELL_ONLINE_SITE

Caddy hostname for HTTPS; http://localhost for local tests.

SHELL_ONLINE_STATE_FILE

Metadata file path. Default /var/lib/shell-online/relay.json.

SHELL_ONLINE_TRUST_PROXY

Enabled by the supplied proxy deployment. Do not expose that trust directly to untrusted clients.

Cloudflare and accounts

The Worker deployment is also available and provides the native MCP channel with its required bindings and keys. An accounts app needs its own identity provider and PostgreSQL.

Follow the operator guide for these deployments. The terminal relay works without an account.