config.toml.example

# Crustly Configuration File
# Copy this file to one of these locations:
#   - Linux/macOS: ~/.config/crustly/config.toml or ~/crustly/config.toml
#   - Windows: %APPDATA%\crustly\config.toml or crustly\config.toml

[database]
# Database file location (stores conversation history)
path = "~/.crustly/crustly.db"

[providers]
# ========================================
# OpenAI-Compatible Provider (Local LLMs)
# ========================================
# Use this for LM Studio, Ollama, LocalAI, etc.
[providers.openai]
enabled = true
base_url = "http://localhost:1234/v1/chat/completions"  # LM Studio default
# ⭐ IMPORTANT: Set this to match the model name loaded in LM Studio!
# Common examples:
#   - qwen2.5-coder-7b-instruct
#   - codellama-7b-instruct
#   - deepseek-coder-6.7b-instruct
#   - llama-3.2-1b-instruct
default_model = "qwen2.5-coder-7b-instruct"

# Other local LLM servers:
# Ollama: base_url = "http://localhost:11434/v1/chat/completions"
# LocalAI: base_url = "http://localhost:8080/v1/chat/completions"

# ========================================
# Official OpenAI Provider
# ========================================
# [providers.openai]
# enabled = true
# api_key = "sk-..."  # Or use OPENAI_API_KEY environment variable
# default_model = "gpt-4-turbo-preview"  # Optional: override default model

# ========================================
# Anthropic Provider (Claude)
# ========================================
# [providers.anthropic]
# enabled = true
# api_key = "sk-ant-..."  # Or use ANTHROPIC_API_KEY environment variable
# default_model = "claude-3-5-sonnet-20240620"  # Optional: override default

# ========================================
# Google Gemini Provider (also serves Gemma models)
# ========================================
# Runs Gemini (gemini-3-pro, gemini-2.5-pro/flash, gemini-2.0-flash) and
# Google's open-weight Gemma models (gemma-4-31b-it, gemma-4-26b-a4b-it,
# gemma-3-27b-it, ...) through the same generateContent API - no local GPU
# or Ollama required, and Gemma usage through this endpoint is free of charge.
# [providers.gemini]
# enabled = true
# api_key = "AIza..."  # Or use GEMINI_API_KEY environment variable
# default_model = "gemini-2.5-flash"  # Or e.g. "gemma-4-31b-it" for Gemma via API
# base_url = "https://generativelanguage.googleapis.com/v1beta"  # Optional override

# ========================================
# Qwen Provider (Local vLLM / DashScope Cloud)
# ========================================
# For local Qwen deployment (vLLM, LM Studio with Qwen models):
# [providers.qwen]
# enabled = true
# base_url = "http://localhost:8000/v1/chat/completions"  # vLLM default
# default_model = "qwen3-8b"
# tool_parser = "hermes"  # Options: "hermes" (XML tags), "native" (✿FUNCTION✿ markers), "openai"
# enable_thinking = true  # Enable Qwen3 thinking mode
# thinking_budget = 5000  # Optional: limit thinking tokens

# Tool parser options:
# - "hermes": Uses <tool_call> XML tags (recommended for vLLM with --tool-call-parser hermes)
# - "native" or "qwen": Uses ✿FUNCTION✿ Unicode markers (official Qwen-Agent format)
# - "openai": Uses standard OpenAI tool_calls format

# Sampling overrides (optional). vLLM's OpenAI-compatible server does not
# apply model-appropriate sampling itself and is prone to repetition/looping
# output without them, so crustly sends Qwen's recommended defaults
# automatically: top_p=0.8 + repetition_penalty=1.05 for Qwen2.5/Coder
# models, top_p=0.8 + top_k=20 for Qwen3 (top_p=0.95 in thinking mode, no
# repetition_penalty). Only set these to override that behavior:
# top_p = 0.8
# top_k = 20               # vLLM/LM Studio extension; local deployments only unless set here
# repetition_penalty = 1.05  # vLLM/LM Studio extension; local deployments only unless set here

# For DashScope cloud API:
# [providers.qwen]
# enabled = true
# api_key = "your-dashscope-key"  # Or use DASHSCOPE_API_KEY env var
# region = "intl"  # "intl" (Singapore) or "cn" (Beijing)
# default_model = "qwen-plus"  # qwen-max, qwen-plus, qwen-turbo
# enable_thinking = false  # Thinking mode for Qwen3 models only

# ========================================
# Native Ollama Provider (via ollama-rs)
# ========================================
# Distinct from providers.openai.base_url pointed at Ollama's OpenAI-compat
# shim above - this one talks to Ollama's own /api/chat protocol and unlocks
# keep_alive/num_ctx control plus runtime performance metrics (tokens/sec,
# model load time) shown in the TUI. Requires building crustly with
# `--features ollama` (or `all-llm`).
# Only ONE [providers.ollama] table is valid per config file - the two
# examples below show alternative values for the *same* table (which model
# to run), not two sections to enable together. Uncomment one, not both.
#
# Option A - Qwen2.5-Coder 7B (default example):
# [providers.ollama]
# enabled = true
# host = "http://localhost:11434"
# default_model = "qwen2.5-coder:7b"
# keep_alive = "5m"    # "-1" (never unload), "0" (unload immediately), or "5m"/"30s"/"2h"
# num_ctx = 8192       # Context window size to request from the model
#
# Option B - Ornith 9B (agentic coding model, MIT license, 256K context):
# ollama pull ornith:9b
# Sampling values below are Ornith's documented recommendation for software
# development tasks (lower for refactoring, e.g. temperature = 0.05).
# [providers.ollama]
# enabled = true
# host = "http://localhost:11434"
# default_model = "ornith:9b"
# keep_alive = "5m"
# num_ctx = 65536       # Model supports up to 262144; 65536 balances context vs. memory/latency
# temperature = 0.10
# top_p = 0.90
# top_k = 20
#
# Option C - Gemma 4 26B A4B (MoE, 8 active / 128 total experts + 1 shared,
# 25.2B total / 3.8B active params, 256K context, native tool calling, vision,
# and thinking):
# ollama pull gemma4:26b
# Sampling values below are Google/Ollama's standardized recommendation
# (ollama.com/library/gemma4:26b) "across all use cases", including agentic
# and tool-calling workflows - see docs/models/gemma-4-26b-a4b/ for the full
# reference. Lower temperature (e.g. 0.1-0.2) is a Crustly-side option if you
# want stricter determinism for tool calls/JSON output, at the cost of
# deviating from the vendor's tuned defaults.
# [providers.ollama]
# enabled = true
# host = "http://localhost:11434"
# default_model = "gemma4:26b"
# keep_alive = "5m"
# num_ctx = 65536       # Model supports up to 262144; 65536 balances context vs. memory/latency
# temperature = 1.0
# top_p = 0.95
# top_k = 64
#
# Other Gemma 4 tags (swap default_model above, same sampling values apply):
#   gemma4:e2b / gemma4:e4b - edge/effective-parameter models, 128K context,
#                             lower RAM (~8-16 GB), also support audio input
#   gemma4:12b              - 128K context, dense, mid-size
#   gemma4:31b               - 256K context, dense, highest quality, heaviest
#   gemma4:31b-cloud         - Ollama-hosted, no local GPU/RAM required
#
# Env var equivalents: OLLAMA_HOST (or OLLAMA_BASE_URL), OLLAMA_MODEL
#
# Model management from the command line (list/pull/delete/show/embed):
#   crustly ollama list
#   crustly ollama pull qwen2.5-coder:7b
#   crustly ollama rm qwen2.5-coder:7b
#   crustly ollama show qwen2.5-coder:7b
#   crustly ollama embed nomic-embed-text "some text to embed"

# ========================================
# llama.cpp (in-process, no external server) - actually *loading* a model
# via [providers.llama_cpp] below requires building crustly with
# `--features llama-cpp` (native C++ compilation, see
# docs/guides/LLAMA_CPP_GUIDE.md before enabling this). Loads a local
# .gguf file directly into the crustly process - no Ollama/LM Studio
# daemon to install or keep running, unlike every other local-inference
# option above. Trade-off: switching models means unloading and reloading
# a multi-GB file (seconds to tens of seconds), not the near-instant swap
# Ollama's server gives you - see llama-cpp-2-integration-plan.md §4.5.
#
# The `crustly llama-cpp list|pull|rm` file-management commands documented
# below are lighter-weight than the above: they need only the
# `gguf-management` feature (on by `default`, no C++ toolchain required),
# so they work even in a plain `cargo build` with no [providers.llama_cpp]
# configured at all - see ccguf-managment-imrpoment-plan.md Phase M0.
# ========================================
# [providers.llama_cpp]
# enabled = true
# model_path = "/home/you/.cache/crustly/models/qwen2.5-coder-7b-instruct-q4_k_m.gguf"
# n_ctx = 8192          # Fixed for the life of the loaded context (unlike Ollama's per-request num_ctx)
# n_gpu_layers = 0      # 0 = CPU only. Requires building with a GPU feature to have any effect -
#                       # see "GPU acceleration" below - otherwise this is a silent no-op (a warning
#                       # is logged at startup if you set it > 0 without one).
# temperature = 0.10
# top_p = 0.90
# top_k = 20
# repeat_penalty = 1.1
# idle_unload_secs = 300   # Auto-unload after 5 min idle, reloaded lazily on the next request. Unset = never.
# models_dir = "/home/you/.cache/crustly/models"  # Used by `crustly llama-cpp list|pull|rm`; defaults to a platform cache dir.
#
# Model management from the command line (list/pull/delete - no `show`,
# unlike Ollama; llama.cpp has no equivalent of `/api/show`):
#   crustly llama-cpp list
#   crustly llama-cpp pull hf:Qwen/Qwen2.5-Coder-7B-Instruct-GGUF/qwen2.5-coder-7b-instruct-q4_k_m.gguf
#   crustly llama-cpp pull https://example.com/direct/path/to/model.gguf
#   crustly llama-cpp rm qwen2.5-coder-7b-instruct-q4_k_m.gguf
#
# The `hf:org/repo/file.gguf` shorthand resolves against Hugging Face and
# verifies the downloaded file's SHA-256 when HF publishes one for it (LFS
# files do); a direct URL has no checksum to verify against and downloads
# with a warning instead.
#
# GPU acceleration: build with one (or more) of `--features
# llama-cpp-cuda`, `llama-cpp-metal`, `llama-cpp-vulkan`, `llama-cpp-rocm`,
# `llama-cpp-opencl`, `llama-cpp-mkl` (each requires its own SDK/toolkit
# installed - see docs/guides/LLAMA_CPP_GUIDE.md), then set n_gpu_layers
# above 0.

# Environment variables for Qwen:
# - QWEN_BASE_URL: Local endpoint URL
# - DASHSCOPE_API_KEY: Cloud API key
# - QWEN_ENABLE_THINKING: Enable/disable thinking mode (true/false)

# ========================================
# Tips for Using Local LLMs
# ========================================
# 1. Make sure LM Studio is running before starting Crustly
# 2. Load a model in LM Studio first
# 3. Set default_model to EXACTLY match the model name shown in LM Studio
# 4. Increase context length in LM Studio if you get overflow errors:
#    - Recommended: 8192 or higher
#    - Location: LM Studio > Model Settings > Context Length