Skip to content
Gray Gray

Set up your box

The box is where Gray actually lives: your conversations, your keys, your agents. One install script sets it up.

  1. Run the installer on the box:

    Terminal window
    curl -fsSL https://get.layergray.com | sudo sh

    It creates a virtualenv, writes an .env, lays down a systemd service (gray-server), starts the server on an internal port (default 8848), and — once the box is on your tailnet — publishes it over HTTPS on port 8443.

  2. Join your tailnet. The installer installs Tailscale when it’s missing, but only you can sign the box in:

    Terminal window
    sudo tailscale up

    Then re-run the install one-liner (it’s safe — it finishes the publish step), or run the exact command it printed:

    Terminal window
    sudo tailscale serve --yes --bg --https=8443 http://127.0.0.1:8848

    Enable MagicDNS and HTTPS certificates in the Tailscale admin console — the box’s address becomes https://<hostname>.<tailnet>.ts.net:8443. Details: Tailscale.

  3. Note the box address and box code. The installer ends on a PAIR YOUR PHONE card with both: the https://…ts.net:8443 address and a one-time box code. The box also prints the code to its console log whenever a first sign-in is attempted (the log line says claim code — same thing):

    self-host: first sign-in needs claim code  3f9c2a7e1b8d4c06

    Lost it? journalctl -u gray-server | grep -i 'claim code'.

    Why a box code? Your box is reachable inside your tailnet, and the first account to sign in owns it. The box code proves that whoever creates that account also has console access to the machine — nobody can adopt your box just by reaching its address. It is used once and then destroyed.

  4. Connect from the app. Create your account (Sign in); the app lands on Connect your box — paste the box address and box code from the installer card and tap Connect box. Gray then scans the box for models and agents — you’ll see Scan complete with what it found.

Prefer Docker?

Section titled “Prefer Docker?”

A compose file ships with the server — see Docker. Note the container path doesn’t manage Tailscale for you.

If something fails

Section titled “If something fails”