Skip to content
Atomic Agent logo Atomic Agent docs

Use with Ollama

Atomic Agent ships with a built-in Ollama preset. Point the agent at your local Ollama server and every model you have pulled becomes available to it. No API key is needed for a local Ollama.

What you need

  • Ollama installed and running (ollama serve starts automatically with the desktop app).
  • Atomic Agent installed (the prebuilt binary bundles its own runtime; Node.js 25.7+ is needed only when running from source).
  • At least one model pulled.

Quick start

  1. Pull a model with Ollama:

    Terminal window
    ollama pull qwen3:8b

  2. Install Atomic Agent:

    Terminal window
    curl -fsSL https://atomicagent.io/install | sh

    On Windows:

    Terminal window
    irm https://atomicagent.io/install.ps1 | iex

  3. Launch the agent:

    Terminal window
    atomic-agent

    In the first-run setup, choose Cloud models, then pick the Ollama (local) preset. The agent lists the models you have pulled; select one and you are done.

Configure by hand

If you prefer editing config directly, add an Ollama entry to the providers array in ~/.atomic-agent/config.json:

{
  "llm": {
    "activeTextProvider": "ollama",
    "providers": [
      { "id": "local-llama", "kind": "llama-server" },
      {
        "id": "ollama",
        "kind": "openai-compatible",
        "baseUrl": "http://localhost:11434",
        "apiKeyEnvVar": "OLLAMA_API_KEY",
        "defaultChatModel": "qwen3:8b"
      }
    ]
  }
}

Keep the { "id": "local-llama", "kind": "llama-server" } entry in providers. The setup wizard writes one; if your config has no llm block yet, add it as shown. It serves embeddings by default, and the config is rejected if activeEmbeddingProvider names a provider that is not in the list.

apiKeyEnvVar tells the agent which variable holds the key for this entry. A local Ollama needs no key, so leave OLLAMA_API_KEY unset. Without apiKeyEnvVar, an openai-compatible entry falls back to OPENAI_COMPAT_API_KEY or OPENAI_API_KEY, and a key you exported for another service would be sent to Ollama.

defaultChatModel must match a tag from ollama list character for character, including the :tag suffix. qwen3 and qwen3:8b are different names to Ollama, and a mismatch fails at request time rather than at startup. Copy the value straight out of ollama list.

Ollama tags change as new families ship, so treat this table as a starting point and confirm the exact tag on ollama.com/search or with ollama list:

ModelGood forApproximate size
qwen3:8bcoding and agentic tool use~5 GB
qwen3:14bstronger reasoning, still laptop-sized~9 GB
qwen3:4blight option for 8 GB machines~2.5 GB
gemma3:12bgeneral reasoning, vision-capable~8 GB
gemma3:4bsmall general-purpose model~3.3 GB

Any model from ollama.com/search works as long as it fits your hardware. Models with tool-use support give the agent the best results.

Ollama Cloud

Atomic Agent also ships an Ollama Cloud preset for Ollama’s hosted service. Pick it the same way you pick the local preset, or configure it by hand:

{
  "llm": {
    "activeTextProvider": "ollama-cloud",
    "providers": [
      { "id": "local-llama", "kind": "llama-server" },
      {
        "id": "ollama-cloud",
        "kind": "openai-compatible",
        "baseUrl": "https://ollama.com",
        "apiKeyEnvVar": "OLLAMA_CLOUD_API_KEY",
        "defaultChatModel": "<model id from ollama.com/search>"
      }
    ]
  }
}

Replace the defaultChatModel placeholder with a cloud model id from ollama.com/search. An openai-compatible entry needs both baseUrl and defaultChatModel; without them the provider fails to load.

Set your key in the OLLAMA_CLOUD_API_KEY environment variable, or in <stateDir>/.env. A hand-written entry must name its key variable with apiKeyEnvVar; without it the agent falls back to OPENAI_COMPAT_API_KEY / OPENAI_API_KEY. The preset writes apiKeyEnvVar for you. It lists available models without a key, but you need one to actually run a request.

Context length

Ollama picks a default context window based on available memory, and on smaller machines that can mean 4k tokens. Agent sessions carry a system prompt, tool definitions, and history, so a short window makes the model silently forget earlier turns.

If answers degrade over a session, raise the context window in Ollama:

  • In the Ollama desktop app: Settings, then Context length.
  • For a manually started server: set the OLLAMA_CONTEXT_LENGTH environment variable before ollama serve, for example OLLAMA_CONTEXT_LENGTH=65536.

A 64k window is the recommended baseline for agent work if your hardware allows it.

Troubleshooting

  • 404 errors on chat requests. Usually a model-name mismatch rather than a URL problem: compare defaultChatModel against ollama list exactly, suffix included. A trailing /v1 on baseUrl is not the cause; it is stripped automatically.
  • Empty model list. Make sure Ollama is running: ollama list should print your models.
  • First-run setup opens when you do not want it. It only opens on a fresh install with no configured backend. To skip it anyway, start with atomic-agent tui --skip-llama-setup, or set ATOMIC_AGENT_TUI_SKIP_LLAMA_SETUP=1.

For the full configuration reference, see Configuration.