FAQ & Troubleshooting

My machine shows offline

The green dot means "this machine's agent is connected to the server right now". If it's grey:

1. Is the computer awake? A sleeping laptop is offline — see Start at Boot.
2. Is the agent running? macOS: menu bar icon present? Linux: systemctl status code-agent (or systemctl --user status code-agent). Windows: check Task Manager.
3. Can it reach the server? From that machine: curl -sI https://your-server-address/. The agent reconnects automatically with backoff — a brief network blip heals itself within a minute.
4. Server just restarted? Everything shows offline for a few seconds while agents reconnect. Normal.

I can't get an HTTPS certificate

Almost always DNS or port 80. Work through the checklist and error table in HTTPS & Domain.

I sign in and am immediately signed out

cookieSecure: true in the server config while you're browsing over plain http://. Use the https:// URL — or, if you really are testing without TLS, set cookieSecure: false temporarily.

macOS says the app "can't be opened"

The app isn't notarized. Right-click → Open → Open (once), or System Settings → Privacy & Security → Open Anyway. The install script normally handles this for you — see Install the Agent.

The quota batteries look stale or empty

They update while sessions run; after hours of inactivity they can lag. Tap the 5h or week battery to force a fresh check. See Usage & Quota.

Two entries for the same computer in Devices

The machine's identity file (~/.code) was reset — by an OS reinstall, a wipe, or a different user account — so it bound again as a new device. Delete the stale entry in Settings → Devices.

Which install did I get — system or userland?

Whoever ran the installer decided: with sudo/root you got the system package and service; without, everything went under $HOME with a systemctl --user service. The uninstall/upgrade scripts detect this automatically.

Where are the logs?

• Agent: ~/.code/logs/ on the machine, plus journalctl --user -u code-agent (Linux userland) or journalctl -u code-agent (root install).
• Server: sudo journalctl -u code-server (containers: podman logs code-server).

Is my code sent to the server?

Session transcripts (what you and Claude say, including code snippets in the conversation) are relayed and stored on the server as history. Your repository itself, files on disk, and your Claude credentials stay on your computer. Self-hosting means all of it stays on hardware you control.