CrewAI with local models: run a team of AI agents on Ollama (Linux, Windows, Mac)

What you get in one minute#

CrewAI is an open-source Python framework (MIT licence) for building a team of AI agents that share work, and with Ollama the whole team can use a model on your own computer instead of a cloud API.

Logo: the official CrewAI project (github.com/crewAIInc/crewAI)

You describe each agent (role, goal, backstory, tools) and each task in text files, and crewai run works through the tasks in order. This guide builds a two-agent team that reads a notes file and writes a short digest, on your machine. Three things decide whether it works: a model that can call tools, a large enough Ollama context window, and switching off the defaults that reach the internet (a cloud model, cloud embeddings, telemetry).

At a glance:

• What it is: a Python framework plus a crewai command. Agents and tasks live in .jsonc files; Python code is optional.
• The local route: each agent points at Ollama on localhost:11434.
• The model must handle tools: pick one with the "tools" badge on ollama.com.
• The setting people miss: Ollama's context window. Its default is small and silently cuts what does not fit.
• Privacy: CrewAI sends anonymous telemetry by default. One environment variable turns it off.
• Free or paid? The framework is free. The company also sells a paid platform; you do not need it.

How it fits together#

You start a crew with crewai run. CrewAI reads crew.jsonc and the agent files, runs the tasks in order, and each agent asks the local Ollama model for its next step. Dashed boxes only happen if you leave a default switched on.

Drawn from the CrewAI docs (installation, LLM connections, telemetry) and the CrewAI source at release 1.15.35, November 2026. Green stays on your machine; red leaves it.

Before you start#

Check Python:

python3 --version

python --version

Checklist:

• [ ] Python 3.10 to 3.13
• [ ] Ollama installed (our Ollama guide covers it)
• [ ] You know which model fits your memory (which local LLM fits your GPU)

Tested on 2026-11-05: Linux = not run, Windows = not run, Mac = not run. Every command and value comes from the official docs and the CrewAI source at release 1.15.35; the commands are not run by DIY Lab Hub.

Step 1: Install Ollama and raise its context size#

Ollama's FAQ says the default context window is 4096 tokens, and its context page says agents should be set to at least 64000. A crew sends role text, task text and tool results in every request, so 4096 fills up fast and the overflow is dropped without an error. qwen3:8b has a 40K window on its library page, so this guide uses 32768. Larger values need more memory.

Linux#

curl -fsSL https://ollama.com/install.sh | sh

If Ollama runs as a systemd service, set the variable in an override: sudo systemctl edit ollama.service, add the two lines below, then sudo systemctl daemon-reload and sudo systemctl restart ollama.

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=32768"

Windows (PowerShell)#

Download the installer from ollama.com/download and run it. Then set the variable for your user and restart Ollama from the tray:

setx OLLAMA_CONTEXT_LENGTH 32768

The Ollama app also has a context length slider in its settings (Ollama context page); use either one.

Mac (Terminal)#

Download the Mac app from ollama.com/download and open it once. The app does not read shell variables, so set it with launchctl (Ollama FAQ), then quit and reopen the app:

launchctl setenv OLLAMA_CONTEXT_LENGTH 32768

Check it worked. ollama ps prints a table. Once a model is loaded (Step 6) its CONTEXT column shows the number you set. Ollama's docs show this layout (expected output from the docs, a different model):

NAME             ID              SIZE      PROCESSOR    CONTEXT    UNTIL
gemma4:latest    c6eb396dbd59    9.6 GB    100% GPU     131072     2 minutes from now

Tip: Do not set OLLAMA_HOST to a bare address like 0.0.0.0 unless you mean to open Ollama to your network. Older CrewAI versions also broke on a scheme-less OLLAMA_HOST (issue #7205, fixed in the 1.15.35 source).

Step 2: Pull a model that handles tools#

A CrewAI agent that has tools asks the model to call them. Ollama's tool calling page describes this as a model feature, and each model on ollama.com carries a "tools" badge when it has it. CrewAI does not publish a list of tested local models, so use Ollama's list: ollama.com/search?c=tools.

This guide uses qwen3:8b as a middle choice. Smaller models tend to handle tools worse; that is our caution, not a CrewAI statement.

Linux#

ollama pull qwen3:8b

Windows (PowerShell)#

ollama pull qwen3:8b

Mac (Terminal)#

Same command as Linux:

ollama pull qwen3:8b

Check it worked. ollama list shows qwen3:8b.

Step 3: Turn telemetry off, then install CrewAI#

Set the opt-out first. crewai create (Step 4) sends an event before you can edit the new project's .env, so the variable must already be in your shell. CrewAI's telemetry page: set CREWAI_DISABLE_TELEMETRY to true, 1, yes or on.

Linux#

echo 'export CREWAI_DISABLE_TELEMETRY=true' >> ~/.bashrc
export CREWAI_DISABLE_TELEMETRY=true
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install crewai

If your shell warns about PATH, the CrewAI docs say to run uv tool update-shell and open a new terminal.

Windows (PowerShell)#

setx CREWAI_DISABLE_TELEMETRY true
$env:CREWAI_DISABLE_TELEMETRY = "true"
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install crewai

If a build fails with fatal error C1083: Cannot open include file: 'float.h' (the chroma-hnswlib package), the docs say to install the Visual Studio Build Tools with "Desktop development with C++".

Mac (Terminal)#

Same commands as Linux, but macOS uses zsh, so write to ~/.zshrc instead of ~/.bashrc:

echo 'export CREWAI_DISABLE_TELEMETRY=true' >> ~/.zshrc
export CREWAI_DISABLE_TELEMETRY=true
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install crewai

Check it worked. In a new terminal run crewai --version, then uv tool list. The docs show the list as the tool name and version, for example crewai v0.102.0 (an old example; yours shows 1.15.x).

Tip: There is no command that shows the telemetry setting. The variable is read when CrewAI starts. Unrecognised values are ignored and leave telemetry on, so write exactly true.

Step 4: Create the project#

The wizard asks about agents, tasks and settings. Step 5 replaces the files, so only two answers matter: choose Ollama if it asks for a provider, and answer n to "Enable crew memory?". The wizard's default is yes (CrewAI source), and memory uses OpenAI embeddings unless you configure another embedder (see Common mistakes).

Linux#

crewai create crew local-notes
cd local_notes

Windows (PowerShell)#

crewai create crew local-notes
cd local_notes

Mac (Terminal)#

Same commands as Linux:

crewai create crew local-notes
cd local_notes

The folder name uses underscores (the docs show latest-ai-development becoming latest_ai_development).

Check it worked. The folder holds agents/, crew.jsonc, .env, knowledge/, skills/, tools/, pyproject.toml and README.md. The docs call this the JSON-first layout. For the older crew.py plus YAML layout, crewai create crew <name> --classic makes it.

Step 5: Write the agents, the task list and a sample file#

Two agents: a reader with the built-in FileReadTool, and a writer. Each has its own llm block pointing at Ollama; this object form (provider, base_url) is the one CrewAI's own project template shows for local endpoints. context_window_size tells CrewAI the window from Step 1; for a model it does not know, CrewAI assumes 8,192 tokens and logs a warning (LLM docs). The commands first remove the generated agent files.

Linux#

rm -f agents/*.jsonc
cat > agents/reader.jsonc <<'EOF'
{
  "role": "Notes reader",
  "goal": "Read the notes file and list every decision and every action item exactly as written",
  "backstory": "You read raw meeting notes. You report only what is in the file and never invent anything.",
  "llm": {
    "model": "qwen3:8b",
    "provider": "ollama",
    "base_url": "http://localhost:11434",
    "temperature": 0,
    "context_window_size": 32768
  },
  "tools": ["FileReadTool"],
  "settings": { "verbose": true, "allow_delegation": false, "max_iter": 8 }
}
EOF
cat > agents/writer.jsonc <<'EOF'
{
  "role": "Digest writer",
  "goal": "Write a short, clear digest for people who missed the meeting",
  "backstory": "You turn lists of decisions and action items into a plain digest of at most 150 words.",
  "llm": {
    "model": "qwen3:8b",
    "provider": "ollama",
    "base_url": "http://localhost:11434",
    "temperature": 0,
    "context_window_size": 32768
  },
  "settings": { "verbose": true, "allow_delegation": false, "max_iter": 8 }
}
EOF
cat > crew.jsonc <<'EOF'
{
  "name": "Notes Digest",
  "agents": ["reader", "writer"],
  "tasks": [
    {
      "name": "read_task",
      "description": "Use the file read tool to read the file {notes_file}. List every decision and every action item with its owner. Do not add anything that is not in the file.",
      "expected_output": "Two bullet lists: decisions, and action items with their owners.",
      "agent": "reader"
    },
    {
      "name": "write_task",
      "description": "Turn the two lists into a digest of at most 150 words for people who missed the meeting.",
      "expected_output": "A short markdown digest.",
      "agent": "writer",
      "context": ["read_task"],
      "output_file": "output/digest.md"
    }
  ],
  "process": "sequential",
  "verbose": true,
  "memory": false,
  "tracing": false,
  "inputs": { "notes_file": "notes.txt" }
}
EOF
cat > notes.txt <<'EOF'
Team call, project Alpha
- Decision: we ship the beta on Friday, not Monday.
- Decision: the old export format is removed in version 2.
- Maria will update the install guide by Wednesday.
- Jon will ask the vendor about the licence renewal.
- Open question: who owns the monitoring dashboard?
EOF
printf 'CREWAI_DISABLE_TELEMETRY=true\nCREWAI_TRACING_ENABLED=false\n' >> .env

Windows (PowerShell)#

Run these in the project folder. The closing '@ of each here-string must start at the beginning of its line.

Remove-Item agents\*.jsonc -ErrorAction SilentlyContinue
Set-Content -Path agents\reader.jsonc -Value @'
{
  "role": "Notes reader",
  "goal": "Read the notes file and list every decision and every action item exactly as written",
  "backstory": "You read raw meeting notes. You report only what is in the file and never invent anything.",
  "llm": {
    "model": "qwen3:8b",
    "provider": "ollama",
    "base_url": "http://localhost:11434",
    "temperature": 0,
    "context_window_size": 32768
  },
  "tools": ["FileReadTool"],
  "settings": { "verbose": true, "allow_delegation": false, "max_iter": 8 }
}
'@
Set-Content -Path agents\writer.jsonc -Value @'
{
  "role": "Digest writer",
  "goal": "Write a short, clear digest for people who missed the meeting",
  "backstory": "You turn lists of decisions and action items into a plain digest of at most 150 words.",
  "llm": {
    "model": "qwen3:8b",
    "provider": "ollama",
    "base_url": "http://localhost:11434",
    "temperature": 0,
    "context_window_size": 32768
  },
  "settings": { "verbose": true, "allow_delegation": false, "max_iter": 8 }
}
'@
Set-Content -Path crew.jsonc -Value @'
{
  "name": "Notes Digest",
  "agents": ["reader", "writer"],
  "tasks": [
    {
      "name": "read_task",
      "description": "Use the file read tool to read the file {notes_file}. List every decision and every action item with its owner. Do not add anything that is not in the file.",
      "expected_output": "Two bullet lists: decisions, and action items with their owners.",
      "agent": "reader"
    },
    {
      "name": "write_task",
      "description": "Turn the two lists into a digest of at most 150 words for people who missed the meeting.",
      "expected_output": "A short markdown digest.",
      "agent": "writer",
      "context": ["read_task"],
      "output_file": "output/digest.md"
    }
  ],
  "process": "sequential",
  "verbose": true,
  "memory": false,
  "tracing": false,
  "inputs": { "notes_file": "notes.txt" }
}
'@
Set-Content -Path notes.txt -Value @'
Team call, project Alpha
- Decision: we ship the beta on Friday, not Monday.
- Decision: the old export format is removed in version 2.
- Maria will update the install guide by Wednesday.
- Jon will ask the vendor about the licence renewal.
- Open question: who owns the monitoring dashboard?
'@
Add-Content -Path .env -Value "CREWAI_DISABLE_TELEMETRY=true"
Add-Content -Path .env -Value "CREWAI_TRACING_ENABLED=false"

Mac (Terminal)#

Same commands as Linux (the cat and printf lines work in zsh).

Check it worked. agents/ holds only reader.jsonc and writer.jsonc, and .env ends with the two lines. JSONC files may contain comments and trailing commas.

Tip: Every agent, and any manager_llm, planning_llm or function_calling_llm, needs its own local llm. One that is missing falls back to an OpenAI model and asks for an API key. Setting "memory": false in crew.jsonc is on purpose: see Common mistakes.

Step 6: Install and run#

crewai install wraps uv sync and installs the project's packages (including the tools package, which holds FileReadTool). crewai run loads crew.jsonc, prompts for any placeholder without a default, and starts the crew.

Linux#

crewai install
crewai run

Windows (PowerShell)#

crewai install
crewai run

Mac (Terminal)#

Same commands as Linux:

crewai install
crewai run

Check it worked. In a second terminal run ollama ps while the crew works: qwen3:8b should be listed, with CONTEXT showing 32768 and PROCESSOR showing GPU or CPU. When the run ends, output/digest.md exists. It should mention the Friday beta, Maria's install guide and Jon's vendor question. If the run screen asks whether to upload an execution trace, answer no (see the telemetry section).

Open source framework or paid platform#

The framework you just used is free. The company also sells a platform around it, which the README calls "a commercial control plane around CrewAI": managed deployment, observability, governance, security and enterprise support.

The docs say tracing "is managed independently from telemetry". In the source, traces from a run that is not logged in stay on your machine until you explicitly agree to upload them.

Telemetry and privacy: what leaves your machine#

With a local Ollama model your prompts and files stay on your computer. CrewAI's own telemetry is a separate stream, and it is on by default.

Collected by default, per the telemetry page: CrewAI and Python versions, a size band for your CPU count, crew metadata (process type, memory on or off, counts of agents and tasks), agent roles, tool names, LLM name and temperature, task success or failure (exception class name only), and that crewai create or crewai run was used. The docs say prompts, task descriptions, backstories, responses and secrets are not collected, and add: "We do collect Tool's names and Agent's roles, so be advised not to include any personal information" there.

Setting share_crew to True on a crew sends much more, including goals, backstories, task descriptions and outputs. Leave it off.

OTEL_SDK_DISABLED also turns CrewAI's telemetry off, but the docs say it does not turn off tracing for the paid platform. Use CREWAI_TRACING_ENABLED=false for that, as in Step 5.

Security and testing#

• Trust what you run. The docs warn: only run JSON crew projects from sources you trust. custom:<name> tools and {"python": ...} references run local Python when the crew loads.
• File access. FileReadTool reads only inside the folder you run from (its base_dir). Do not point base_dir at a folder with secrets.
• Secrets. Local Ollama needs no key. If you add a cloud provider, put the key in the project's .env, which CrewAI's .gitignore already excludes. On Linux and Mac run chmod 600 .env.
• Keep Ollama local. It listens on 127.0.0.1:11434 by default (Ollama FAQ).
• Smoke test. Before a long crew, test the model alone with one request, using Ollama's OpenAI-compatible endpoint:

curl http://localhost:11434/v1/models

curl.exe http://localhost:11434/v1/models

Check it worked. A JSON list that includes qwen3:8b. No answer means Ollama is not running.

Tip: Ollama's OpenAI-compatible page lists tools as supported and tool_choice as not supported. A model can be fine in the Ollama chat window and still behave oddly as a crew agent. Test with your real task, not only a chat.

Common mistakes#

Each row comes from CrewAI's docs, its source, or a real GitHub issue (state as read in November 2026). The last row is about AI assistants.

Tip: Keep the first run tiny: one file, two short tasks, max_iter at 8. If a small model loops, a low max_iter stops it.

Tip: When something fails, read the verbose output to see which step failed: the model call, the tool call, or the task hand-off. Each has a different fix.

Tip: If you change qwen3:8b, change it in every agent file and in ollama pull. A name Ollama does not have gives an error about the API connection.

Troubleshooting#

Exact error texts#

Failed to connect to OpenAI API: Connection error. is the message in issue #7205 (closed September 2026) when OLLAMA_HOST had no scheme. The 1.15.35 source adds the scheme, port and /v1 itself.

Value error, The OPENAI_API_KEY environment variable is not set. is the message in issue #4028 (closed January 2026) for a search tool that ignored its Ollama settings. A dummy key then fails against OpenAI. Find what still calls OpenAI instead.

ImportError: ... and the LiteLLM fallback package is not installed is issue #8723 (closed October 2026), for CrewAI 1.15.31 and 1.15.32 with LiteLLM older than 1.97.0. You only meet it if you installed LiteLLM.

Known bugs (open on the day we read the tracker)#

• #7895 (opened October 2026): an agent with reasoning turned on can loop forever because bare "READY" verdicts are missed. Leave reasoning off for local models.
• #7259 (opened September 2026): crew.usage_metrics multiplies token counts by the number of agents sharing one LLM instance. Treat the totals with care.

Updates and backups#

Update. CrewAI releases often (twelve releases between early October and early November 2026, up to 1.15.35), and some change behaviour: the changelog lists the removal of CrewAgentExecutor in 1.15.29. Update on purpose, not by accident. The CLI and each project upgrade separately.

uv tool install crewai --upgrade
crewai --version

uv tool install crewai --upgrade
crewai --version

In the project, the CrewAI upgrade guide says to bump the constraint and re-lock with uv add, then sync. Replace <version> with the number you want:

uv add "crewai[tools]>=<version>"
crewai install
uv pip show crewai

uv add "crewai[tools]>=<version>"
crewai install
uv pip show crewai

Ollama updates itself on Mac and Windows; on Linux re-run the install script (Ollama FAQ). Try updates on a copy of the project first.

Back up. A crew is a folder of text files. Back up the project without the .venv folder, which crewai install can rebuild. Project data such as saved memory lives under .crewai/ in the project unless you set CREWAI_STORAGE_DIR (CrewAI memory docs). Run this from the folder that holds local_notes.

mkdir -p ~/backups
tar --exclude='local_notes/.venv' -czf ~/backups/local_notes-$(date +%F).tar.gz local_notes

New-Item -ItemType Directory -Force $HOME\backups | Out-Null
tar --exclude="local_notes/.venv" -czf "$HOME\backups\local_notes-$(Get-Date -Format yyyy-MM-dd).tar.gz" local_notes

Schedule it with cron at 03:00 on Linux and Mac, or Windows Task Scheduler. Keep the archive private: .env is inside it.

Restore test. Unpack into an empty folder and list it:

mkdir restore-test && tar -xzf ~/backups/local_notes-<date>.tar.gz -C restore-test
ls restore-test/local_notes

New-Item -ItemType Directory restore-test | Out-Null
tar -xzf "$HOME\backups\local_notes-<date>.tar.gz" -C restore-test
Get-ChildItem restore-test\local_notes

If you see crew.jsonc and the agents folder, the backup works.

Performance and resources#

• No official numbers. CrewAI publishes no RAM, speed or model-size figures for local models, and we took no timings.
• Every agent step is a model call. More tasks, tools and context mean more and slower calls.
• Context costs memory. Ollama's FAQ says memory scales with the parallel requests times the context length. If ollama ps shows the model on the CPU, lower the context or pick a smaller model.
• Agent limits from the docs: max_iter (default 20; it has changed between releases, so set it), max_rpm, max_execution_time and max_retry_limit.
• Watch it. ollama ps shows the CONTEXT and the PROCESSOR split while the crew runs.

FAQ#

Is CrewAI still maintained? Yes. The repository is not archived or renamed, and the latest release (1.15.35) is from November 2026. Review versions before updating.

Does it work offline? The docs do not promise it. The model and the file tool run locally; installing needs the internet. Test on your own network.

Which model should I use? One with the "tools" badge on ollama.com that fits your memory, such as qwen3:8b; try a larger one if answers are weak.

Do I have to use JSON files? No. Python code and the older YAML layout (--classic) still work; the docs recommend JSON for new projects.

Do I need the paid platform? No. Nothing in this guide needs an account.

Can I add web search? Yes (the README uses the Serper tool), but that sends queries to a search service and needs its key. Leave it out to stay local.

Sources#

• CrewAI on GitHub (MIT licence, release 1.15.35) and its README - read November 2026
• CrewAI installation and Build your first crew - read November 2026
• Connect CrewAI to LLMs and LLMs concepts - read November 2026
• Agents, Crews and Memory - read November 2026
• Telemetry and Tracing - read November 2026
• Upgrading CrewAI and File Read tool - read November 2026
• CrewAI source at release 1.15.35 (project template, LLM routing, telemetry module) - read November 2026
• Ollama FAQ, context length, tool calling and OpenAI compatibility - read November 2026
• Ollama models with tools and the library pages for qwen3, llama3.1, llama3.2, gpt-oss - read November 2026
• GitHub issues in crewAIInc/crewAI: #103, #447, #2164, #3622, #4028, #4694, #4695, #7205, #7259, #7895, #8723 - read November 2026
• Related guides: Ollama, Which local LLM fits your GPU, Aider with a local model, LiteLLM proxy, Langfuse tracing

Checked against the official docs on 2026-11-05.