Troubleshooting

The daemon isn’t responding

Check liveness:

curl http://127.0.0.1:1234/health

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

Build can’t fetch llama-server

build.rs downloads a pinned llama-server release with curl and tar (PowerShell on Windows). If the download fails (offline, proxy, unsupported platform), either:

• Point Lattis at an existing binary: export LATTIS_LLAMA_SERVER=/path/to/llama-server, or
• Skip vendoring and rely on one on PATH: export LATTIS_SKIP_VENDOR=1.

MLX models don’t appear

MLX is optional and only offered when mlx_lm is importable by the interpreter Lattis finds. Verify:

python3 -c "import mlx_lm.server"   # must exit 0

If you use a virtualenv, pin it: export LATTIS_MLX_PYTHON=/path/to/venv/bin/python, then restart the daemon. MLX is Apple Silicon only; on other platforms MLX models are always hidden. Remember only one MLX model is served at a time — loading another swaps it.

Port already in use

The API uses 127.0.0.1:1234 and the router child uses the next port up. If 1234 is taken, change the port in the app’s settings (or config.json) and restart the daemon.

A cloud model is rejected

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

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.

Still stuck? Open an issue at github.com/ZetaMinusOne/lattis/issues.