Box code (claim code)

The box code is the one-time 16-character code that binds the first account to a fresh box. The app calls it a box code; the server’s log calls it a claim code — same thing. Why it exists: Set up your box.

Where to find it

The installer prints it on its final PAIR YOUR PHONE card, and the box logs it whenever a first sign-in is attempted:

journalctl -u gray-server | grep -i 'claim code'
# self-host: first sign-in needs claim code  3f9c2a7e1b8d4c06

Try the sign-in again in the app while watching the log — the line repeats on each sign-in attempt until the box is claimed.

Docker: docker compose logs -f gray.

Lost it / no console scroll-back

The code persists (until used) in the vault auth state. On the box:

sudo cat /var/lib/voice-brain/selfhost_auth.json
# "claim_code": "3f9c2a7e1b8d4c06"

If you can read that file, you have console access — which is exactly the proof the claim step asks for.

”This box is already claimed”

A box code only works on an unclaimed box — it is consumed the moment the first account claims it, and the app can’t adopt a box someone else owns. If the app says the box is already claimed:

• It’s yours (set up with another email)? Tap Sign in as this box’s owner and use the email you set it up with — a claimed box only issues sign-in codes to that address; any other email gets silence, on purpose.
• Taking the box over? Have its current owner remove their account in the app (Me → Account), then sign in fresh — the box prints a new box code for you. No owner around? Reset the box: curl -fsSL https://get.layergray.com | sudo sh -s -- --uninstall --purge-data, then install again.

Asked for a box code, but you already claimed this box

The claim gate only applies to an unclaimed box. Seeing it again after claiming means the vault auth state was removed or you’re talking to a different box (rebuilt VPS, restored snapshot). Sign in fresh — the box prints a new box code — or restore the vault from backup to keep the original account.

Pre-baking for automation

Set GRAY_CLAIM_CODE in the box env before first start (the installer’s non-interactive mode does this), then feed the same value to the app at claim time.