Troubleshooting

Agents

An agent isn’t in the picker

Lattis only lists agents whose CLI it can find on your PATH. If Claude, Codex, Pi, or OpenCode is missing, install its CLI so the command (claude, codex, pi, or opencode) runs in a terminal, then reopen the picker. If no agents are detected at all, Lattis lists all four as a fallback — but launching one that isn’t installed will fail.

An agent launches but can’t reach a model

Agents run against the models Lattis serves. Make sure you’ve connected a local model server or connected a provider, and that the model id the agent is configured to use actually appears in GET /v1/models. Lattis points each agent at its gateway automatically, so you shouldn’t need to set any base URL yourself.

Opening a branch reattaches instead of starting fresh

That’s intended — re-opening a branch with a running session reconnects to it so you don’t spawn duplicates. To start over, close the existing agent tab first, then open the branch again.

Pull requests & CI

A branch shows no PR status

PR and CI state come from the GitHub API with your connected GitHub account. Check the connection in Settings › Accounts › GitHub — the card shows Connected as @you when everything is set, and offers Connect GitHub (a short device code you enter at github.com/login/device) when not.

If the card says the token was rejected, your authorization was revoked or expired on GitHub’s side — click Connect GitHub to sign in again. Upgrading from an older Lattis that used the gh CLI? Your gh sign-in is imported automatically on the first launch after the update.

A PR shows red / blocked but CI looks fine

“Blocked” covers more than a failed check: merge conflicts, requested changes, and a branch that’s behind a protected base all show red. If the base requires branches to be up to date, use Pull Latest Main to update the branch — GitHub won’t allow the merge until you do.

Models & providers

A cloud model is rejected

• Confirm the provider has a connected account.
• Re-check the credential: POST /control/remote/{provider}/account/{account_id}/key for an API key, or reconnect OAuth with POST /control/remote/{provider}/account/{account_id}/connect.
• Confirm the model id is exact (e.g. claude-opus-4-8, gpt-5.5). List what’s available with GET /v1/models.

Local models don’t appear

Local models come from the servers you connect (LM Studio, Ollama, llama.cpp, vLLM, …) — see Local Models. Make sure the server is running and its OpenAI-compatible API is reachable at the account’s base URL (e.g. http://localhost:11434/v1 for Ollama). A server that goes down simply drops out of GET /v1/models until it’s back.

MCP servers

A server’s tools don’t show up

• Check the launch command and arguments under Settings → MCP — Lattis runs them as given, so the command must be on your PATH (e.g. npx for npm packages).
• Make sure the server is enabled. Toggling it takes effect live; no restart needed.
• The model finds MCP tools by searching for them, so phrase requests in terms of what you want done — the tools surface on demand rather than being listed up front.

Conversations & code

Code execution isn’t available

Code execution is on by default but can be scoped. If it’s not running, check your configuration: agent.code_exec_enabled may be false, or agent.code_exec_models may list models that exclude the one you’re using. It’s also sandboxed by design — code can’t reach the network or your files, so tasks needing those will fail inside it.

Updates

The app won’t update

Automatic updates apply to the installed desktop app, not to source/development builds — for those, pull and rebuild. If an update download fails, try again later; your data and settings are untouched by a failed update. See Keeping Lattis Updated.

The daemon & ports

The daemon isn’t responding

Check liveness:

curl http://127.0.0.1:5288/health

If it fails, make sure Lattis is running (open the app, or enable launch-on-login). When launched on login, its output is in daemon.log in the data directory.

Port already in use

The API uses 127.0.0.1:5288. If the port is taken, change it in the app’s settings (or config.json) and restart the daemon.

Upgrading from an older Lattis? The default port used to be 1234, which is also LM Studio’s — configs still on it move to 5288 automatically on the first start after updating.

Reset state

Stop the daemon (POST /control/shutdown), then inspect or remove files in the data directory. Deleting config.json resets settings to defaults; deleting remote_auth.json clears cloud credentials; deleting accounts.json clears your named accounts. Your saved conversations live in chats/.