Troubleshooting

The engine won’t start

Settings › Engine shows whether the engine is running. Restart, next to it, starts it again; your sessions and accounts are kept.

• On first launch, the engine downloads from the npm registry. If that fails, check your connection, VPN or firewall, then click Try Again. If it says the download didn’t match or isn’t signed, something on your network changed the file: try another network.
• If it takes too long, macOS may be waiting for you to allow access to a folder. Look for that dialog, which can be behind other windows, and click Allow.

A sign-in doesn’t finish

Click Open the Page Again if the browser page closed, or Cancel and connect again. If the provider offers an API key, that’s a reliable alternative. See Accounts.

A model is missing

The model picker lists models from providers you’ve connected, plus the free ones. Connect the provider in Accounts (⇧ ⌘ K).

Can’t read or change files in a folder

macOS asks before an app uses your Desktop, Documents or Downloads folders. If you clicked Don’t Allow, turn access back on in System Settings › Privacy & Security › Files & Folders, under Kuvo Code.

Logs

The engine’s logs are in ~/Library/Application Support/run.kuvo.code/opencode/data/opencode/log; Settings › Engine › Show in Finder opens the folder above it.

Report a problem

Open an issue on GitHub with your Kuvo Code and macOS versions, what happened, and the end of the newest engine log if the engine is involved. Logs can include your prompts, code and file paths, so remove anything private first.

Problems with the agent itself that also happen in opencode belong with opencode. Report security problems privately.