Support

Start here when your keep misbehaves. Setting up for the first time? See Install.

Look first

keepcmd service status
keepcmd status

The first says whether the service is running, whether it survives logging out, and where the log is. The second shows the keep's connection, its sandbox, the harnesses it found and its agents.

The log is ~/.keepcmd/daemon.log (also journalctl --user -u keepcmd). It's designed to hold ids, types, timings and error codes, not your messages or prompts.

Common problems

The app says my keep is offline

• Check it's running: keepcmd service status. If there's no service, install it: keepcmd service install.
• Stops when you log out, or doesn't come back after a reboot? Turn on lingering, once: sudo loginctl enable-linger $USER.
• Check the machine is online, then look at the end of the log.
• To restart it: systemctl --user restart keepcmd. (Under the service, keepcmd stop alone gets it restarted.)

The app asks me to pair again

• Run keepcmd hub pair and scan the new code from the Keep tab. Each code works once, for 10 minutes.
• If it says this device was removed, check keepcmd hub devices.

"Update needed"

• Your keep or the app is too old for the other. Update the keep with keepcmd hub update --now, and the app from its store.

The installer says there's no build for this machine

• Keep Cmd is built for Linux on x86_64 and aarch64. Other platforms aren't supported yet.

Setup says this machine can't run agents safely

• Agents need a Landlock sandbox: Linux 6.12 or newer, with landlock in cat /sys/kernel/security/lsm. Upgrade the kernel, or enable Landlock in your boot settings, then run keepcmd hub setup again.

An agent's harness isn't found

• Run keepcmd hub harness to see what the keep finds and where. Keep Cmd never installs a harness: install it yourself, as the same user that runs the keep.
• The service sees a shorter PATH than your shell. It looks in ~/.local/bin, npm's global folder and the system's. If yours is elsewhere, tell the keep: keepcmd hub harness path claude /path/to/claude (or codex, gemini, copilot, pi), then restart the keep.
• pi needs Node 22.19 or newer. To choose which Node: keepcmd hub harness node pi /path/to/node.

Agents won't start

• Run keepcmd hub network status. If network control is unavailable, agents won't start until it is. Run once: sudo ~/.local/bin/keepcmd hub network install.

The sandbox refuses something

• Each agent works in its own folder, behind a sandbox, and reaches the network only through the keep's proxy. Websites are open by default; your local network, this machine's own services, and ports other than web ones aren't.
• When an agent needs something outside that, it asks you in Loop Cmd. Allow answers once. A folder outside the agent's sandbox needs Always allow, which adds it and restarts the agent.

Phones on my Wi-Fi can't reach the keep (Hearth Cmd)

• A firewall (ufw or firewalld) may be blocking the keep's port. sudo ~/.local/bin/keepcmd hub network install allows it from your local network only. Loop Cmd doesn't need this.

I lost my PIN, or all my devices

• On the new device, tap Forgot your PIN? and Use the console. Then, at the keep's computer, run keepcmd hub approve and check the code matches the one on the device.
• Too many wrong PINs lock sign-ins by PIN. To unlock them: keepcmd hub custody unlock.

Help us help you

Optional, and off by default: keepcmd hub health-reports on sends the relay a daily report of the keep's version, uptime, sandbox and update health, and error counts by type. Nothing else. keepcmd hub health-reports show prints one.

Contact

Still stuck? Email support@vergelabs.org with your keepcmd version, your Linux distribution, and what you saw. Please don't send keys, recovery words, messages or prompts: we don't need them to help.