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).
• Node.js 25.7.0 or newer.
• At least one model pulled.

Quick start

1. Pull a model with Ollama:

   ollama pull qwen3:8b

2. Install Atomic Agent:

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

   On Windows:

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

3. Launch the agent:

   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 provider to ~/.atomic-agent/config.json:

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

Note

Store baseUrl without a trailing /v1 — that is the canonical form. If you do paste one in, the agent strips it automatically before every request, so http://localhost:11434 and http://localhost:11434/v1 both work. Only /v1 is stripped; a different path like /api/v2 is left alone.

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.

Recommended models

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:

Model	Good for	Approximate size
qwen3:8b	coding and agentic tool use	~5 GB
qwen3:14b	stronger reasoning, still laptop-sized	~9 GB
qwen3:4b	light option for 8 GB machines	~2.5 GB
gemma3:12b	general reasoning, vision-capable	~8 GB
gemma3:4b	small 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": "ollama-cloud",
        "kind": "openai-compatible",
        "baseUrl": "https://ollama.com"
      }
    ]
  }
}

Set your key in the OLLAMA_CLOUD_API_KEY environment variable, or in <stateDir>/.env. The preset lists available models without a key, but you need one to actually run a request.

This is not local

Unlike local Ollama, the cloud preset sends your prompts off your machine to Ollama’s servers. Everything the agent puts in the prompt goes with them — file contents it has read, tool output, and memory. Use the local preset if you want the local-first guarantee.

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=32768.

A 32k window is a good 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.
• The local models wizard appears even though Ollama is configured. Start with atomic-agent tui --skip-llama-setup, or set ATOMIC_AGENT_TUI_SKIP_LLAMA_SETUP=1.

For the full configuration reference, see Configuration.