Troubleshooting

When something doesn't behave, start here.

Installing

The USB stick won't boot. Re-write the ISO (a bad write is the usual cause), and make sure the machine's boot menu is set to the USB device. Some firmware needs Secure Boot disabled.

It boots but the screen is blank. Use the Server build for headless machines, or the Desktop build for ones with a display. A desktop image needs supported graphics — try it in a VM first if unsure.

Updates

An update seems stuck. Updates stage and apply on reboot. Check status with bootc status (command line) and reboot to apply.

Something broke after an update. Roll back — Kiki keeps the previous image:

sudo bootc rollback && sudo systemctl reboot

A failed boot rolls back automatically, so you shouldn't end up stuck.

The agent

Kiki isn't doing anything. Check the agent service:

sudo systemctl status agentd
sudo systemctl restart agentd

It's asking before every step. That's Assisted mode working as intended. Switch modes from the HUD if you want it to act on its own.

Responses are slow or it won't use a big model. On-device models are limited by your hardware. Pick a smaller default model, or opt into cloud inference by enabling allow_remote in the configuration.

Connectivity & cloud

A device won't connect to the cloud. Re-run enrollment — the code is single-use and short-lived, so get a fresh one. Confirm the device has internet.

It's not showing in the dashboard. Make sure you're signed in to the same account and the correct context (personal vs. team) is selected.

Privacy check

Did something leave my device? By default, no. Inference is local-first and sync is opt-in. Set trace_decisions = true in the configuration to log exactly why the router chose each provider.

Still stuck?

File an issue on the relevant GitHub repo, or check the glossary if a term is unfamiliar.