ChatOllama is an open-source agentic app for running AI agents with hosted or
local models. The primary user entry point today is the installable
chatollama-agent command-line app.
Requires Node.js 24 or newer.
npm install --global chatollama-agent
chatollama-agentSet the API key for any provider you want to use before starting the CLI. These are the provider credentials recognized by the current release:
| Provider | Environment variable |
|---|---|
| OpenAI | OPENAI_API_KEY |
| Anthropic | ANTHROPIC_API_KEY |
| Google Gemini | GEMINI_API_KEY, falling back to GOOGLE_GENERATIVE_AI_API_KEY |
| DeepSeek | DEEPSEEK_API_KEY |
| OpenRouter | OPENROUTER_API_KEY |
| Ollama (OpenAI-compatible) | OLLAMA_API_KEY (optional; defaults to the non-secret value ollama) |
For example:
export OPENAI_API_KEY='replace-with-your-key'
chatollama-agentThe CLI also recognizes these explicit startup overrides:
| Variable | Purpose |
|---|---|
AGENT_PROVIDER |
Select openai, anthropic, google, deepseek, openrouter, or ollama |
AGENT_MODEL |
Select the model ID |
AGENT_BASE_URL |
Override the selected provider's API endpoint |
AGENT_API_KEY |
Override the selected provider's credential |
AGENT_MAX_STEPS |
Set the positive-integer step budget for each prompt (default: 4) |
Use provider and model overrides together when you want a specific startup model:
AGENT_PROVIDER=openai AGENT_MODEL=gpt-5-mini chatollama-agentAGENT_PROVIDER or AGENT_MODEL takes precedence over a saved selection.
AGENT_BASE_URL and AGENT_API_KEY override its endpoint and credential
without changing its provider/model identity. A mapped provider credential is
still required to add that provider's built-in models to automatic discovery;
AGENT_API_KEY alone does not do so.
Compatibility note: Ollama is supported as one OpenAI-compatible provider
alongside the providers above. The CLI still falls back to ollama/qwen3:8b
when no model is available, and AGENT_MODEL without AGENT_PROVIDER uses
Ollama. This keeps the command loop available but does not mean that model is
installed or reachable. To select it explicitly, set AGENT_PROVIDER=ollama
and, when needed, AGENT_BASE_URL.
On startup, ChatOllama discovers available models. Configured remote providers contribute a built-in model catalog; OpenAI also performs filtered model discovery, and an available Ollama endpoint contributes its installed models. Discovery failures produce warnings without preventing the CLI from opening.
At the prompt:
- Enter a message and press Return. Follow-up messages continue the same in-memory conversation.
- The Runtime may call
read_file,list_directory,grep, andfind_filesto inspect the directory where the CLI was started. Both terminal modes show each tool's validated input, execution status, and bounded result. - Enter
/modelsto view available models and choose one. In an interactive terminal, use the arrow keys and Return; press Escape to cancel. - Enter
/model <provider>/<model-id>to switch directly, for example/model openrouter/openai/gpt-5-mini. The model must appear in/models. - Enter
/newto clear conversation history while keeping the selected model. - Press Ctrl+C during a response to cancel that response and keep the CLI open. Press Ctrl+C while idle to quit.
- Enter
/exitto quit cleanly.
A successful model selection applies to later messages and is saved as the next startup default. Conversations and API keys are not saved.
For plain or scripted input, /models prints a numbered list instead of the
interactive picker:
printf '/models\n/exit\n' | chatollama-agentTo run a deterministic tool loop without a provider, network request, or paid API key:
pnpm install --frozen-lockfile
pnpm agent:tool-loop-demoThe demo performs two real model steps with AI SDK MockLanguageModelV3: the
first requests the safe UTC-time tool, and the second receives its result and
streams the final answer.
To exercise all six workspace tools without a provider or network request:
pnpm agent:workspace-tools-demoThe CLI startup directory is the workspace root. Tool paths must be relative to
that root; absolute paths, .. escapes, prefix-confusion paths, and symlinks
that resolve outside it are rejected. Read/search results are capped and report
truncation. write_file and exact edit_file use atomic replacement, serialize
changes to the same path, and reject content over 1,048,576 bytes. Successful
read_file, write_file, and edit_file results include a complete-content
sha256:<hex> version. write_file and edit_file accept an optional
expectedVersion; a stale value returns VERSION_CONFLICT without changing
the file. edit_file supports the legacy single exact replacement and batches
of up to 100 replacements: every literal oldText must match exactly once in
the original content, ranges must be non-overlapping, and the whole batch is
atomic. The cumulative edit input and resulting content are each limited to
1,048,576 UTF-8 bytes; matching is never fuzzy. They do not expose shell
commands.
For configuration precedence, saved preference locations, plain-mode behavior, and provider-specific examples, see the Agent CLI guide.
ChatOllama is an app for running AI agents, not an SDK for building them.
This README should be updated with every release that changes user-visible behavior.
