Models and connections

Separate stored data from model execution#

Kyalulu owns stored characters, personas, worlds, conversation state, and memory. The selected provider performs generation. Routing through LE does not transfer ownership of the character's canonical data to LE. Changing models can change writing style and instruction following, but registering a model does not prepare its weights or establish its quality.

For your first setup, complete the Mock check in Getting started. With an external server, generation inputs are transmitted even if your saved data stays local. See Data and privacy for the distinction.

Choose a model served by LE#

1. Start LE's le-daemon and check LE_API_URL. The default is http://127.0.0.1:8130.
2. Set LE_API_TOKEN for the Kyalulu API, or make LE's generated token file readable. Its default Windows location is %LOCALAPPDATA%/kyalulu-le/api-token.
3. Use Status diagnostics, or /le status and /le models in the chat composer, to check readiness and IDs.
4. Select a served model from Kyalulu's model list.

If LE's internal ID is ollama/qwen3.5:9b, Kyalulu exposes it automatically as le:ollama/qwen3.5:9b. This illustrates the ID format; it does not mean the model is installed automatically. Automatic discovery needs no YAML. For an explicit definition, example-le.yaml uses provider.type: le and provider.model: ollama/qwen3.5:9b, without the le: prefix in the latter.

Use /le load <id> to load a GGUF and /le unload [id] to unload it. Command results are not stored as conversation messages. Loading needs time and RAM or VRAM; being listed does not establish readiness to generate. The API holds the token and does not pass it to the browser.

Connect directly to LM Studio or Ollama#

For direct connections without LE, copy models/example-lmstudio.yaml or models/example-ollama.yaml to a new filename. Give it a unique id and the actual model name. This is a basic configuration derived from the public Ollama example:

id: my-qwen2-local
display_name: "My local Qwen2"
provider:
  type: ollama
  model: qwen2:7b
context_length: 8192
recommended_generation:
  temperature: 0.8
  top_p: 0.9

id identifies the model within Kyalulu; provider.model is the name accepted by the engine. Prepare that model in Ollama and check OLLAMA_URL in .env. For LM Studio, use provider.type: lm_studio and match the loaded server model ID and LM_STUDIO_URL. The default URLs are http://127.0.0.1:11434 and http://127.0.0.1:1234/v1, respectively.

Restarting the API synchronizes YAML definitions to the database. YAML is the source of truth for these model definitions; SQLite is a cache. Context length and quantization metadata do not guarantee performance and must match the model and loading configuration. Check diagnostics after changes, then start with a short conversation when you are ready to generate.

Configure an OpenAI-compatible API and understand its limits#

models/example-openai.yaml demonstrates provider.type: openai_compatible. Copy it, match the model ID to the actual provider, and set the base URL and key in .env:

OPENAI_COMPATIBLE_URL=https://api.openai.com/v1
OPENAI_COMPATIBLE_API_KEY=YOUR_API_KEY
LLM_BASE_URL=
LLM_API_KEY=

This illustrates a URL from the public configuration, not entitlement to or verified operation of a particular model. Do not append /chat/completions to the URL. When set, LLM_BASE_URL and LLM_API_KEY take precedence as generic aliases, so inspect both sets of variables to avoid routing to an unintended endpoint.

For authentication errors, check the URL and key; for an unknown model, check the provider's ID; for loading failures or delays, check the engine and available memory first. Continue to Characters when adjusting character settings, or return to the index.