FAQ

Common questions about installation, configuration, agents, and troubleshooting.

Installation

Which Ollama models do I need?

Model	Purpose	Required?
qwen3:8b	Language generation (main)	Yes
qwen3-embedding:0.6b	Vector memory embeddings	Only for memory_mode
llava	Screenshot captioning	Optional

Pull with ollama pull <model>. Update model names in config/config.py if you use alternatives.

Can I run without a GPU?

Yes. PyTorch falls back to CPU. Install CPU-only PyTorch:

uv pip install torch torchaudio torchvision --index-url https://download.pytorch.org/whl/cpu

Expect slower transcription and TTS synthesis (3-5x slower than GPU).

Why does uv sync take so long?

The dependency tree includes heavy packages (transformers, chromadb, sentence-transformers, torch). First install can take 10+ minutes on a slow connection. Subsequent installs use the uv cache.

Configuration

How do I add a new agent?

Edit config/config.py — add an entry with a name, personality prompt, and traits. No code changes needed. The factory (build_agents()) creates agents from config data at startup.

See the Custom Agents Guide for a step-by-step walkthrough.

How do I change the TTS model?

Set tts_model in config/config.py to any Chatterbox-compatible model path. The faster fork supports multiple voice models — check the Chatterbox docs for available options.

How do I enable/disable modes?

Three ways:

1. Voice: Say "analysis mode on" or "memory mode off"
2. UI: Toggle checkboxes in the Tauri sidebar (Modes panel)
3. Config: Set boolean flags in config/config.py (requires restart)

The ten modes are: analysis, mute, auto_chat, memory, control, cloud, training, remote_mic, silence, legacy.

Tool Calling

Why isn't my tool executing?

Tool calls route through the RealToolHost security pipeline. Common issues:

1. Missing manifest: The tool must have a registered ToolManifest in tools/schemas.py
2. Autonomy policy: Check your autonomy tier — higher side-effect levels require approval
3. Persistent denial: Previously denied tools stay denied until revoked
4. Timeout exceeded: Long-running tools are cancelled after their manifest timeout

Check the audit log for details: look for ToolExecutionError or ToolDeniedError events.

How do I add a custom tool?

1. Define the tool schema in tools/schemas.py
2. Register a handler via ToolHostAdapter.register_handlers()
3. Create a ToolManifest with the appropriate side-effect level
4. The agent can now invoke it through the security pipeline

See the Security Guide for details on manifests and autonomy tiers.

Troubleshooting

"ModuleNotFoundError: No module named 'chatterbox'"

The TTS engine is installed separately:

git clone -b faster https://github.com/rsxdalv/chatterbox.git chatterbox
cd chatterbox && uv pip install -e . && cd ..

"Ollama connection refused"

Ensure Ollama is running: ollama serve or start the Ollama desktop app. The backend connects to 127.0.0.1:11434 by default.

TTS sounds distorted

Check your audio output device. On Windows, set VECTOR_MIC_INDEX to the correct device index if using loopback recording for remote mic mode.

"pynini not found" error on TTS startup

conda install -c conda-forge pynini

This is a conda-only dependency — pip wheels don't exist for pynini.

The app hangs during startup

Check the console output. Common causes:

• Model loading timeout: Large models (embedding, reranker) take time to load on CPU
• ChromaDB lock: Another instance may be running (rm -rf data/chromadb/*.lock)
• Port conflict: API server needs 127.0.0.1:8765 free

Data

How do I back up conversations?

Conversations are stored in a SQLite database (WAL mode). Copy the .db file from the data directory while the app is stopped, or use the backup command via the API:

curl -H "X-Session-Secret: <your-secret>" http://127.0.0.1:8765/commands \
  -d '{"command": "backup_conversations", "path": "backups/chat_$(date).json"}'

How do I clear the vector memory?

Delete the ChromaDB directory:

rm -rf data/chromadb/*

Embeddings are rebuildable from the SQLite store. Restarting with memory mode enabled will re-upsert documents.

Advanced

Can I use remote models?

Yes, enable cloud_mode to route through a cloud model (configured in config/config.py as language_model_cloud). All other modes use local Ollama inference.

How do I change the API port?

Edit the host and port parameters in core/api/api_server.py::ApiServer.__init__() — defaults to 127.0.0.1:8765.

Is there a REST API for external clients?

The local API server supports two endpoints:

• GET /events — SSE event stream (agent responses, mode changes, status)
• POST /commands — Typed commands (29 command schemas) with JSON body

Authentication requires the X-Session-Secret header. See the API Reference for schema details.