goose: the open-source AI agent for your terminal and desktop, with a local model (Linux, Windows, Mac)

What you get in one minute#

goose is a free, open-source AI agent that runs on your own computer as a desktop app or a command-line tool: you give it a task, and it uses a language model plus tools (shell commands, file edits, MCP extensions) to carry the task out.

Logo: the official goose project (github.com/aaif-goose/goose)

goose is not only for code: its README calls it "a general-purpose AI agent". It can use a cloud model with your API key, or a model on your own machine through Ollama. This guide takes the local route and focuses on what decides whether it works and whether it is safe: tool calling, context size and the permission mode.

Where it lives now. goose started as block/goose. Block contributed it to the Agentic AI Foundation (AAIF) at the Linux Foundation (announced December 2025), and the repository is now aaif-goose/goose. The old block/goose address redirects. The docs are at goose-docs.ai. The project is alive: v1.57.0 came out in October 2026 and the main branch had commits in November 2026.

At a glance:

• What it is: a desktop app (macOS, Linux, Windows) and a CLI, built in Rust.
• What it changes: files and anything your shell can reach. It is autonomous by default.
• Local model: through Ollama (localhost:11434), or the built-in llama.cpp provider in the desktop app.
• The catch with local models: goose depends heavily on tool calling. Models without it can only chat.
• First settings to change: permission mode (to approve or smart approve), then the context size.
• Extensions: built on the Model Context Protocol (MCP). Every extension is code that runs on your machine.

How it fits together#

goose sends your task and its tool list to the model. The model answers with a tool call. goose checks the permission mode, then runs the tool through an extension.

Drawn from the goose docs (providers, permissions, logging) and the Ollama docs, November 2026. Green stays on your machine; red only happens if you configure a cloud provider.

Before you start#

The goose docs publish no RAM or disk minimum, so plan from the model. Our guide Which local LLM fits your GPU helps with that.

Checklist:

• [ ] Ollama answers on localhost:11434 (ollama --version works)
• [ ] You chose a model that supports tool calling
• [ ] Your project is committed, so every goose edit is visible in git diff
• [ ] You know where your config lives (see Updates and backups)

Not run by DIY Lab Hub. Every command and value comes from the official goose and Ollama docs and the sources listed at the end, read in November 2026.

Step 1: Install Ollama and pull a tool-calling model#

If Ollama already runs, pull the model and go on. The model name is the docs' own example; pick a size that fits your memory.

Linux#

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

Windows (PowerShell)#

Download the installer from ollama.com/download and run it. Ollama then runs from the tray. Then:

ollama pull qwen2.5

Mac (Terminal)#

Download the app from ollama.com/download and open it once. Then:

ollama pull qwen2.5

Check it worked. Run ollama list. The model appears in the list. Ollama binds 127.0.0.1 port 11434 by default (Ollama FAQ).

Tip: Choose the model for tool calling first, size second. The goose docs say DeepSeek models from the Ollama library do not support tool calling, and goose then has little it can do on its own.

Step 2: Raise Ollama's context window#

goose's docs say that if goose is "having trouble using extensions or is ignoring .goosehints", the model's default context is probably too small (they name 2048 on one page and 4096 on another; Ollama's FAQ says 4096). Ollama's context page advises at least 64000 tokens for agents and warns that more context needs more memory.

Linux#

If you start Ollama yourself:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

If Ollama runs as a systemd service, use the override the Ollama FAQ describes: sudo systemctl edit ollama.service, add Environment="OLLAMA_CONTEXT_LENGTH=64000" under [Service], then sudo systemctl daemon-reload and sudo systemctl restart ollama.

Windows (PowerShell)#

Open the Ollama app's settings and move the context length slider (Ollama's context page). Quit and start Ollama again if you changed it.

Mac (Terminal)#

Same: use the context length slider in the Ollama app's settings.

Check it worked. Send one message through Ollama, then run ollama ps. The CONTEXT column shows the number, and PROCESSOR shows whether the model sits on the GPU. Ollama's docs show this layout:

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

goose also has GOOSE_INPUT_LIMIT, which "maps to num_ctx" for Ollama requests. Use one of the two, not both with different numbers.

Step 3: Install goose#

You can install the desktop app, the CLI, or both. This guide uses the CLI and notes the desktop route at each step.

Linux#

CLI:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

The desktop app is a DEB, RPM or Flatpak from the install page. On Debian or Ubuntu: sudo dpkg -i <file>.deb. If the download fails, the docs say you may need sudo apt install bzip2.

Windows (PowerShell)#

The docs give a PowerShell route that downloads the script first, so you can read it before running it:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

The script installs to %USERPROFILE%\.local\bin. If goose warns that it is not on your PATH, the docs add it for PowerShell like this, then restart PowerShell:

if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -ItemType File -Force }
Add-Content -Path $PROFILE -Value '$env:PATH = "$env:USERPROFILE\.local\bin;$env:PATH"'

The desktop app is a zip from the install page; unzip it and run the executable.

Mac (Terminal)#

Same script as Linux, or Homebrew:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
brew install block-goose-cli

Use one of the two. For the desktop app: download the zip (Apple Silicon or Intel), or brew install --cask block-goose. The Homebrew names still say block; that is the official name in the docs.

Check it worked. Open a new terminal:

goose --version
goose info

goose info shows the version, the config file location, session storage and logs (CLI commands page).

Tip: Piping a script into bash runs whatever the address returns. To read it first, download download_cli.sh to a file, open it, then run it.

Step 4: Connect goose to Ollama#

On first use goose asks for a provider. The CLI starts a configuration mode; you can also run it yourself.

Linux#

goose configure

Choose Configure Providers, then Ollama. goose asks for OLLAMA_HOST: enter http://localhost:11434. Then enter the model name, qwen2.5 here. The docs' own transcript ends with "Configuration saved successfully".

Windows (PowerShell)#

Same: run goose configure and follow the same choices. If goose reports a keyring error, the docs tell Windows users to choose not to store to the keyring, or to set the key as an environment variable. Ollama itself needs no key.

Mac (Terminal)#

Same as Linux: goose configure.

For the desktop app: Settings, then Models, then Configure providers, then Ollama. The docs add that all locally installed Ollama models then appear in the model list.

Check it worked. Run a one-shot task that does not touch files and does not save a session:

goose run --no-session -t "Reply with the word ready."

You should see the model's reply. If goose says it cannot reach http://localhost:11434/v1/chat/completions, Ollama is not running or the model is not pulled (Troubleshooting).

Tip: The docs show a one-process override: GOOSE_PROVIDER and GOOSE_MODEL environment variables beat the config file for that process. We did not find a documented Ollama example for the provider id, so confirm the spelling with goose info before you rely on it.

Step 5: Set the permission mode before the first task#

This is the safety step. goose's docs warn: "Autonomous Mode is applied by default." In that mode goose can modify and delete files and use extensions without asking.

Linux#

Inside a running session you can change the mode with /mode approve, /mode smart_approve, /mode auto or /mode chat. To set the default, run goose configure, choose goose settings, then goose mode. Or set it in ~/.config/goose/config.yaml:

GOOSE_MODE: "smart_approve"

Windows (PowerShell)#

Same menu and the same /mode commands. The config file is %APPDATA%\Block\goose\config\config.yaml.

Mac (Terminal)#

Same as Linux. In the desktop app: sidebar, Settings, Chat, then Default Mode. Each session has its own mode; the default only affects new sessions.

Check it worked. Start goose session, ask for a harmless file change in a test folder, and confirm goose shows Allow and Deny buttons or prompts. goose asks only for tools it classifies as "write" tools; the docs call that "best effort", interpreted by your LLM. A small local model may classify badly, so read each request.

Tip: Approve mode is only a speed bump if you click Allow every time without reading. Read the exact command. Put your project in git first, so git diff shows what changed.

Step 6: Add an extension (MCP) the careful way#

goose's extensions are MCP servers. The Developer extension (shell and file editing) is on by default. Other built-ins include Computer Controller, Memory, Tutorial and Auto Visualiser. Each extension you add also adds tools, and the docs say goose performs best with fewer than 25 tools enabled in total.

Linux#

goose configure

Choose Add Extension, then Command-line Extension, enter a name, the command and a timeout. The docs' example command is npx -y @modelcontextprotocol/server-memory, which needs Node.js. You can also try one for a single session without saving it:

goose session --with-extension "memory:npx -y @modelcontextprotocol/server-memory"

Windows (PowerShell)#

Same commands. The docs add one Windows fix: if Node.js-based extensions fail with "Node.js installer script not found", goose expects Node.js in C:\Program Files\nodejs\, and a symbolic link from your real install path fixes it.

Mac (Terminal)#

Same as Linux. Desktop route for all three: sidebar, Extensions, Add custom extension.

Check it worked. In a session, ask goose which extensions are active, or open Extensions in the desktop app and see the new one switched on.

What to know before you add one:

• It runs as you. A command-line extension is a program started with your rights. Add only extensions you trust.
• goose scans packages, but not perfectly. It checks npx and uvx extensions against the OSV malware database; if that service is down, extensions still install.
• Narrow the tools. The config key available_tools limits what an extension exposes. Fewer tools also helps small local models.

Local models and tool calling: what to expect#

The docs are direct: "goose extensively uses tool calling, so models without it can only do chat completion. If using models without tool calling, all goose extensions must be disabled."

Real reports show the limits. In issue #6883 (closed March 2026) a Qwen3-coder model returned XML-style tool calls instead of structured ones once many tools were enabled. In issue #7968 (closed May 2026) a small local model on macOS produced a plain "write" command instead of a tool call; the maintainer listed the toolshim and the built-in provider as the newer routes. In issue #6507 (closed) a model seemed to forget the conversation; the answer was to set OLLAMA_CONTEXT_LENGTH to something reasonable.

The practical rule: a model that chats well can still fail as an agent. Test with a small, reversible task first.

Security and testing#

• Autonomous by default. See Step 5. This is the main risk, and it applies to local models too.
• Where your data goes. The docs say goose logs and sessions stay on your machine; the LLM and tools "may have their own logs and privacy considerations". With local Ollama, prompts go to 127.0.0.1. Ollama's cloud models are processed in the cloud.
• Telemetry. Anonymous usage data is opt-in (goose asks on first use; GOOSE_TELEMETRY_ENABLED is false by default). Change it with goose configure, then goose settings, then Telemetry.
• Prompt injection detection. Optional: SECURITY_PROMPT_ENABLED: true in config.yaml. The docs call it "a safeguard, not a guarantee".
• Credential files. Issue #13171 (open, October 2026) asks how to stop an agent reading a credential file through shell commands; no per-file block is documented. Keep real secrets out of the folder goose works in.
• Secrets storage. API keys go in the system keyring, or secrets.yaml if the keyring is off. Never commit that file.
• goose serve. The optional ACP server listens on 127.0.0.1:3284 by default and needs GOOSE_SERVER__SECRET_KEY unless you pass --dangerously-unauthenticated. Do not bind it to 0.0.0.0 on a shared network. goose is a local app, so there is no HTTPS or reverse-proxy step in this guide.
• Functional test. The goose run --no-session -t ... command from Step 4, with ollama ps in a second terminal.

Common mistakes#

Each row comes from the goose docs or a real issue in the aaif-goose/goose tracker (state and date as read in November 2026). The last row is about AI assistants.

Tip: Make the first session a throwaway: a small git repo, approve mode, one tiny task such as "add a docstring to one function". Read the diff.

Tip: If goose seems to forget instructions halfway through a task, check ollama ps before you change anything else. A context that is too small looks exactly like a model that is not smart enough.

Tip: Keep .goosehints short. goose adds it to the system prompt on every request, so a long file eats context a small local model cannot spare.

Troubleshooting#

Exact error texts#

ExecutionError("error sending request for url (http://localhost:11434/v1/chat/completions)") is quoted on goose's Known Issues page for the Ollama provider: the model was not downloaded or Ollama was not running.

Error Failed to access secure storage (keyring): ... The name org.freedesktop.secrets was not provided by any .service files is the Linux keyring failure. Set GOOSE_DISABLE_KEYRING=1 or use environment variables.

Known bugs (open on November 2026)#

• #11951 (September 2026): the Ollama provider never calls /api/chat, so Ollama's think setting for reasoning models such as Qwen3 cannot be switched off.
• #13260 (October 2026): Desktop 1.57.0 can store an assistant reply without showing it; it is in the database but missing in the chat pane.
• #12905 (October 2026): on Windows, an OAuth token above 2560 characters cannot be saved to the Credential Manager, so a remote extension fails after sign-in.

Updates and backups#

Update. Update the CLI with its own command (Homebrew users can let Homebrew handle it instead):

goose update

goose update

goose update --canary installs the development version. Do not use it on a machine you depend on. Version 1.57.0 came out in October 2026 and a few Desktop issues are open against it (see Known bugs). If you need to stay on a known version, the install script accepts GOOSE_VERSION.

Back up your settings and sessions. goose is not a server and has no container volume, so there is no ~/docker_volumes folder for it. Your data is its config and its session database. Leave the secrets file out of the backup; the commands below skip secrets.yaml. Paths come from the docs' Configuration Files, Logging and Known Issues pages.

Linux and Mac:

mkdir -p ~/backups
tar --exclude=secrets.yaml -czf ~/backups/goose-$(date +%F).tar.gz -C ~ .config/goose .local/share/goose

Windows PowerShell:

New-Item -ItemType Directory -Force "$HOME\backups\goose" | Out-Null
robocopy "$env:APPDATA\Block\goose" "$HOME\backups\goose" /E /XF secrets.yaml

Robocopy returns codes below 8 for success. Schedule either command with cron at 03:00 (Linux and Mac) or Windows Task Scheduler. API keys stored in the system keyring are not in these files. Note them separately in your password manager.

Restore test. Extract into a throwaway folder and look at what is there:

mkdir -p /tmp/goose-restore && tar -xzf ~/backups/goose-<date>.tar.gz -C /tmp/goose-restore
ls /tmp/goose-restore/.config/goose

If config.yaml is in the list, the archive is good.

Performance and resources#

• Context memory. A bigger context needs more memory. Ollama's FAQ says RAM scales with OLLAMA_NUM_PARALLEL times OLLAMA_CONTEXT_LENGTH.
• VRAM defaults. Ollama's context page: under 24 GiB, 4k; 24 to 48 GiB, 32k; 48 GiB or more, 256k. It advises at least 64000 tokens for agents and coding tools.
• Tool count. The goose docs recommend fewer than 25 enabled tools. Fewer tools means fewer tokens in every request.
• Monitoring. ollama ps shows CONTEXT and PROCESSOR. goose session --debug prints full tool output.
• No numbers here. goose publishes no RAM or speed figures for local models, and we took no timings.

FAQ#

Is goose still maintained, and why does GitHub say aaif-goose? Yes. Block contributed it to the Agentic AI Foundation at the Linux Foundation (announced December 2025) and the repository is now aaif-goose/goose. The old block/goose link redirects. The latest release in our check was 1.57.0 in October 2026, with commits in November 2026.

Does goose run without internet? The docs say a local model lets you "work entirely offline". Extensions that call the web, and npx or uvx downloads, need a network. Test it on your own setup.

How is goose different from the coding agents on this site? Aider edits files in a git repo and commits each change. OpenCode is another terminal agent for Ollama. goose is broader: desktop app plus CLI, MCP extensions and a general-purpose scope.

Can goose use my MCP servers? Yes, over stdio or Streamable HTTP. SSE is not supported. Our Open WebUI MCP guide covers the same protocol from the chat side.

Sources#

• goose repository (aaif-goose/goose), README, LICENSE (Apache 2.0) and v1.57.0 release - read November 2026
• Linux Foundation: formation of the Agentic AI Foundation (December 2025) - read November 2026
• goose quickstart and installation - read November 2026
• goose providers and local LLMs - read November 2026
• goose permission modes and tool permissions - read November 2026
• goose extensions, configuration files, environment variables and CLI commands - read November 2026
• goose logging, usage data, security and prompt injection detection - read November 2026
• goose known issues and .goosehints - read November 2026
• goose blog: built-in local inference (April 2026) - read November 2026
• goose install scripts and for PowerShell - read November 2026
• Ollama FAQ, context length and Linux install - read November 2026
• GitHub issues in aaif-goose/goose: #6883, #7968, #6507, #6117, #9119, #6287, #11951, #13260, #13198, #12905, #13171 - read November 2026

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