Configuration

Where settings come from

Each source overrides the one before it:

1. Built-in defaults
2. andromeda.yml (or andromeda.yaml) in the workspace, the project's copy, --config PATH or ANDROMEDA_CONFIG
3. .env and the real environment
4. Command-line flags such as --model or --memory, and live changes with /config, /model or /permissions

Start from the committed template:

cp andromeda.example.yml andromeda.yml

Keeping everything in andromeda.yml

Credentials can live in andromeda.yml too, so one file holds your whole setup:

• Settings such as agent.openai.api_key, memory.qdrant.api_key or whatsapp.calls.access_token go at their normal path.
• MCP server credentials go in that server's mcp.servers.<name>.env block.
• Anything read straight from the environment (GMAIL_*, HF_TOKEN) goes in the top-level env: map. It is exported at startup to Andromeda, its workers and its MCP servers; a variable already set in the shell or .env wins.

env:
  HF_TOKEN: hf_...
  OLLAMA_CONTEXT_WINDOW: "32768"   # beats a global OLLAMA_CONTEXT_LENGTH

mcp:
  servers:
    postgres:
      command: bun
      args: [run, mcp/postgres/server.ts]
      env: { POSTGRES_USER: me, POSTGRES_PASSWORD: ..., POSTGRES_DB: app }

Model & reasoning

The default chat model is gpt-oss:20b. Change it with agent.model, OLLAMA_MODEL, --model, or /model during a session.

ModelSettings and Reasoning mirror the OpenAI Agents SDK. Each engine maps those controls to the parameters its API supports:

import { Agent, ModelSettings, Reasoning } from "./src/libs/index.ts";

const agent = new Agent({
  name: "deep-researcher",
  model: "gpt-oss:20b",
  modelSettings: new ModelSettings({
    reasoning: new Reasoning({ mode: "pro", effort: "medium", context: "current_turn" }),
  }),
});

• effort: minimal becomes low; xhigh and max become high.
• context: "current_turn" (default) keeps reasoning between a turn's tool calls and drops it afterwards, which is how models such as gpt-oss are trained. all_turns replays every old trace and tends to cause overthinking.

During a session:

Docker Model Runner

Select Docker Model Runner as the chat and embedding engine. Docker Desktop users must enable Model Runner and host TCP access on port 12434. Pull the models you want to use:

docker model pull ai/smollm2
docker model pull ai/nomic-embed-text-v2-moe

Configure Andromeda with Docker Hub model IDs, including their namespace:

agent:
  engine: docker-model-runner
  model: ai/smollm2
  docker_model_runner:
    url: http://localhost:12434

memory:
  provider: qdrant
  semantic_recall:
    enabled: true
    embed_model: ai/nomic-embed-text-v2-moe
  qdrant:
    collection: andromeda_memory_dmr

The default URL is for Andromeda running on the host. A Docker Desktop container can use http://model-runner.docker.internal. Override the URL with DOCKER_MODEL_RUNNER_URL.

The DMR OpenAI-compatible API supports chat, tool calls, streaming and embeddings. Its documented parameter set is narrower than llama.cpp: strict JSON-schema and model-specific reasoning controls are not available. The example models above do not support vision; image analysis needs a vision-capable DMR model.

Ollama setup

With semantic recall on, Andromeda uses two Ollama runners: one pinned for embeddings and one rotating between chat, vision and image models. Ollama's server limits must be set before it starts:

launchctl setenv OLLAMA_MAX_LOADED_MODELS 2
launchctl setenv OLLAMA_NUM_PARALLEL 1
osascript -e 'quit app "Ollama"'
open -a Ollama

agent:
  ollama:
    keep_alive: 10m          # chat model
    embed_keep_alive: -1     # keep the embedding model loaded
    max_loaded_models: 2
    num_parallel: 1

The first request after a model swap (for example to the vision model) is slower while the replacement loads.

Tell Andromeda the context size Ollama actually uses so it can show usage and compact in time:

OLLAMA_CONTEXT_WINDOW=32768 bun run main.ts

Point at another server with OLLAMA_HOST. /doctor checks the connection and whether the model supports tools and thinking.

llama.cpp

agent.engine: llamacpp runs models with llama-server instead of Ollama. Andromeda starts the server with the app and stops it on exit, serving one GGUF model to every role. Install it with brew install llama.cpp, then:

agent:
  model: gemma4:26b-mlx      # still the name /model and /doctor show
  context_window: 32768
  engine: llamacpp
  llamacpp:
    hf_repo: ggml-org/gemma-3-4b-it-GGUF:Q4_K_M
    parallel: 4

On first launch Andromeda downloads the model into data/models/, with progress in the transcript, then starts the server. Later launches use the file on disk. The UI starts right away; the first model call waits until the model has loaded.

Set HF_TOKEN in .env or the env: map of andromeda.yml for gated repositories. The server log is .andromeda/llama-server-<port>.log, and a server that dies is restarted on the next request.

Chat templates

llama-server renders the Jinja template inside the GGUF, and some are strict. Gemma 3's, for example, allows one leading system message and strictly alternating turns. llamacpp.chat_template.messages controls how Andromeda's history is converted:

• native sends system, user, assistant and tool roles as is. Qwen, gpt-oss and Llama 3.x take it.
• alternating merges system messages and turns tool results into user turns, for Gemma 3 and older Mistral templates.
• auto (default) starts native and switches to alternating when the template rejects the turn order.

andromeda.yml reference

The top-level sections. andromeda.example.yml documents every key with comments.

A typical starting point:

agent:
  model: gpt-oss:20b
  reasoning:
    effort: medium
    context: current_turn
  max_parallel_tools: 6
  max_tool_iterations: 10
  permission_mode: auto      # auto | plan | ask
  confirm_destructive: true
  context_window: 32768
  planning: true
  # extra_dirs: [~/Documents/notes]

memory:
  provider: local            # none | local | qdrant
  semantic_recall:
    enabled: true
    embed_model: mxbai-embed-large:335m

voice:
  provider: kokoro

ui:
  show_thinking: true
  recaps: true
  tips: true

Environment variables

Every setting has an environment override, which wins over andromeda.yml. The most useful:

Running through Temporal

For a dashboard of workflow status and worker progress, run turns through Temporal. Start the server and UI with Docker, then a worker:

docker compose -f docker-compose.temporal.yml up -d   # in the Python project
bun run main.ts temporal worker

Submit a normal turn from another terminal:

bun run main.ts temporal run "Explain how this project is structured"

The temporal command delegates to the Python project's Temporal adapter, so install its optional temporal dependency there.

Open http://localhost:8080 to see the durable workflow and activity history. The worker prints structured events (run_started, tool_started, run_finished, …). Set TEMPORAL_ADDRESS when the server runs on another machine.