Use with Ollama

Short answer. Ollama serves its API on http://localhost:11434 (it binds 127.0.0.1:11434 by default). The Ollama desktop app starts the server for you; without the app, run ollama serve. To check that it is up and see which models you have, run:

curl http://localhost:11434/api/tags

A JSON list of models means the server is running. Failed to connect means it is not. Atomic Agent ships a built-in Ollama (local) preset that points at this address, so once the server answers you can pick it in the desktop app or the terminal and choose a model. No API key is needed for a local Ollama.

Ollama CLI cheat sheet

These are the commands you need most often. The full list is in the Ollama CLI reference.

Command	What it does
ollama serve	Starts the API server on port 11434
ollama pull qwen3:8b	Downloads a model
ollama ls	Lists downloaded models (same names the API uses)
ollama ps	Shows loaded models, GPU/CPU split and context size
ollama run qwen3:8b	Chats with a model in the terminal
ollama stop qwen3:8b	Unloads a running model
ollama rm qwen3:8b	Deletes a model
ollama serve --help	Lists the environment variables the server reads

Change the Ollama port or address

Ollama reads its bind address from OLLAMA_HOST. To move it to another port, or to listen on your network:

OLLAMA_HOST=127.0.0.1:11435 ollama serve   # another port
OLLAMA_HOST=0.0.0.0:11434 ollama serve     # reachable from other machines

If Ollama runs as the macOS app, set the variable with launchctl setenv and restart the app; on Linux with systemd, add it to the service with systemctl edit ollama.service. Both are described in the Ollama FAQ.

Common Ollama errors

• address already in use on ollama serve. Something already listens on 11434, usually the Ollama app itself. You do not need a second server: run the curl check above. If it answers, Ollama is ready.
• Failed to connect to localhost port 11434 / connection refused. The server is not running. Open the Ollama app or run ollama serve, then check again.
• Model not found (404). The name you asked for does not match a downloaded model. Run ollama ls and copy the name exactly, including the tag after the colon. qwen3 and qwen3:8b are different names.
• Slow answers, ollama ps shows a CPU share. The model did not fit in GPU memory. Pick a smaller model or a shorter context. Supported GPUs are listed in Ollama hardware support.

Use Ollama with Atomic Agent

Under the hood the preset is an openai-compatible provider with base URL http://localhost:11434. Atomic Agent lists models from Ollama’s /v1/models endpoint and chats through /v1/chat/completions, which Ollama documents in its OpenAI compatibility page.

Desktop app

1. Start Ollama and pull at least one model (ollama pull qwen3:8b).

2. Open Atomic Agent. On the first-run screen, click Already run Ollama or LM Studio? Use it instead, or pick the Cloud models card. Despite the name, that list also holds the model apps on your computer.

3. Choose Ollama (local). There is no key screen for it. Pick a model from the list Ollama returns.

Already set up? Open Settings › Models › Cloud providers, click Add provider and choose Ollama (local).

Terminal

1. Install Atomic Agent:

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

   On Windows:

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

2. Launch it with atomic-agent. In the first-run setup, choose Cloud models, then the Ollama (local) preset, then a model.

3. Later, add it from the LLM tab: run /llm, open the Cloud pane, press n and pick Ollama (local). Switch to it with /llm provider ollama, and change models with /model.

Pointed the llama.cpp URL at Ollama?

The External pane (terminal) and Custom server tab (desktop) are for llama.cpp servers. If you type an address on port 11434 there, Atomic Agent recognises Ollama, refuses to save it as llama.cpp and offers the Ollama provider instead, with your URL filled in.

Configure by hand

Add an entry to the providers array in ~/.atomic-agent/config.json (or <stateDir>/config.json if you set ATOMIC_AGENT_STATE_DIR):

{
  "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. The setup wizard writes one, it serves embeddings by default, and the config is rejected if activeEmbeddingProvider names a provider that is not in the list. The llm block has no dotted keys for atomic-agent config set, so edit the file or use the wizard.

apiKeyEnvVar names the variable that holds this entry’s key. A local Ollama needs none, so leave OLLAMA_API_KEY unset and requests go out without an Authorization header. Without apiKeyEnvVar, an openai-compatible entry falls back to OPENAI_COMPAT_API_KEY or OPENAI_API_KEY, and a key exported for another service would be sent to Ollama.

defaultChatModel must match a name from ollama ls character for character. Store baseUrl without /v1; if you paste one, the agent strips a trailing /v1 before every request.

Ollama on another machine

When you pick Ollama (local) from the list, it saves http://localhost:11434. (An Ollama address typed into the llama.cpp field is kept as you typed it when the agent hands you over to the Ollama provider.) For Ollama on a server or another PC, start it with OLLAMA_HOST=0.0.0.0:11434, then add an OpenAI-compatible provider (desktop: OpenAI-compatible API (custom base URL)) with base URL http://<that-machine>:11434. The wizard asks for a key for non-local addresses; a stock Ollama does not check keys, so any value works.

Context length

Agent sessions carry a system prompt, tool definitions and history, so a short context window makes the model forget earlier turns. Ollama picks its default from your GPU memory: 4k tokens under 24 GiB of VRAM, 32k from 24 to 48 GiB, 256k above that, and it recommends at least 64000 tokens for agents (Ollama: context length).

Atomic Agent reads only model names from Ollama, not the window size, so set the context on the Ollama side:

• In the Ollama app: Settings, then the context length slider.
• For a server you start yourself: OLLAMA_CONTEXT_LENGTH=65536 ollama serve.

Check the result in the CONTEXT column of ollama ps.

Tool calls and model choice

With Ollama, Atomic Agent sends its tools in the OpenAI tools field and relies on the model to answer with tool calls. Pick a model whose Ollama page lists tool support. Ollama tags change often, so confirm exact names on ollama.com/search or with ollama ls. If you want tool calls constrained by a grammar instead, use the agent’s own llama.cpp backend: see Use with llama.cpp.

Ollama Cloud

The terminal agent also ships an Ollama Cloud preset (https://ollama.com, key in OLLAMA_CLOUD_API_KEY); the desktop app does not list it. In the terminal, pick it the same way as the local preset; it lists models without a key, but you need one to run a request.

This is not local

The cloud preset sends your prompts to Ollama’s servers, including everything the agent puts in the prompt: file contents it has read, tool output and memory. Use the local preset when you want the model to run on your own hardware.

Troubleshooting in Atomic Agent

• Empty model list. Ollama is not running or has no models. curl http://localhost:11434/api/tags should list them.
• 404 on chat requests. Usually a model-name mismatch, not a URL problem. Compare defaultChatModel with ollama ls, tag included.
• Answers lose track of the task. Raise the context length (see above).
• First-run setup opens when you do not want it. It opens only when no backend is configured. To skip it, start with atomic-agent tui --skip-llama-setup or set ATOMIC_AGENT_TUI_SKIP_LLAMA_SETUP=1.

FAQ

What port does Ollama use?

Port 11434. Ollama binds 127.0.0.1:11434 by default, and you can change it with OLLAMA_HOST, for example OLLAMA_HOST=127.0.0.1:11435 ollama serve.

What does ollama serve do?

It starts the Ollama API server. The desktop app runs it in the background, so you only need the command when you run Ollama without the app, on a server, or with custom environment variables.

How do I know Ollama is running?

Run curl http://localhost:11434/api/tags. A JSON list of models means it is running; a connection error means it is not.

Does Atomic Agent need an API key for Ollama?

No, not for a local Ollama. The preset saves without a key and sends no Authorization header. Ollama Cloud does need a key.

Can Atomic Agent download models through Ollama?

No. Atomic Agent uses Ollama only as a provider; you pull models with ollama pull. The agent’s own model downloads (GGUF files from Hugging Face) belong to its built-in llama.cpp backend.

For the full configuration reference, see Configuration.

Related

• Use with LM Studio and Use with llama.cpp
• Ollama vs llama.cpp and LM Studio vs Ollama
• How to run an AI agent offline