Quickstart (Docker)

Run Gray on any machine with Docker.

1. Get the code

git clone <gray-self-host-repo-url> gray
cd gray

2. Configure

cp .env.example .env

Fill in at minimum:

• OPENAI_API_KEY — for voice
• ANTHROPIC_API_KEY — for the brain (or use a logged-in Claude CLI)
• VB_ORG_ID — from the Gray enterprise console
• VB_SELFHOST_TOKEN — from the same console (org → Allow self-host)

To let the brain work on existing data, mount it in docker-compose.yml and point VB_BRAIN_CWD / VB_FILE_ROOT at it.

3. Run

docker compose up -d
docker compose logs -f gray

Watch the logs — you should see the box pass the hub gate (Gray verifies your subscription is active).

4. Front it

The container binds to 127.0.0.1:8848. Put it behind something safe:

• A reverse proxy with TLS (Caddy, nginx, Traefik).
• A VPN (Tailscale →).
• An SSH tunnel.

Don’t bind a public interface without authentication in front.

5. Connect Gray

In the native app: Settings → I run my own instance → enter your URL.

Or, as a PWA: open the URL in Safari, Share → Add to Home Screen.

Operating it

Action	Command
Status	docker compose ps
Logs	docker compose logs -f gray
Restart	docker compose restart gray
Update	git pull && docker compose pull && docker compose up -d