Skip to main content
AI Choice EngineAI Choice Engine
Browse decision tools
← All setup guides

Block · Setup guide

How to set up Goose

Install the open-source Goose CLI from the AAIF goose docs (repo moved from block/goose), configure one hosted or local model provider, and start in a disposable repository with a read-only explanation. Goose can execute tools and edit files through its terminal or desktop surface, so the first session should establish provider billing, secret storage, telemetry, and permission expectations first.

Goose

terminal · checked August 8, 2026

~12 minBeginner
Start installOpen GooseCompare itBuyer guide

The “Open Goose” link goes to the vendor site. It is not an affiliate-tracked link on this page — no commission is claimed for that click. Affiliate disclosure.

Critical: finish install before closing the window

Keep the installer terminal open until you see a success message. If you used an admin window, do not close it until verification works. Then open a new Terminal or PowerShell window and run the verify step — PATH updates rarely apply to shells that were already open, especially on Windows.

Before you begin

  • macOS, Linux, WSL, or Windows PowerShell.
  • A terminal and a small practice repository without credentials.
  • An API key or account for a supported model provider, or a local provider such as Ollama.
  • Git installed if you want reviewable diffs and easy rollback.

Authentication

Interactive provider setup with goose configure

Account: A supported model-provider account/API key, or a local model server

Goose is the client, not the model host. goose configure selects a provider and model and stores secrets in the system keyring when available, or in the separate secrets configuration when keyring storage is unavailable.

Install or open it

1. Get the harness ready

These steps are written for beginners. On Mac, Terminal is the black/white text window where you type commands. On Windows, use PowerShell or Terminal. Use the OS tabs to hide steps that are not for your computer, then copy one command at a time.

  1. 01

    Open Terminal on a Mac

    Mac

    Click the Spotlight search icon (magnifying glass) at the top-right of the menu bar, or press Command (⌘) + Space. Type Terminal and press Return. A text window opens — that is where you paste the install commands below. Leave it open.

  2. 02

    Open Terminal or PowerShell on Windows

    Windows

    Press the Windows key, type Terminal or PowerShell, then press Enter. Use that window for the commands below. If Windows asks for permission to run a script or install software, read the prompt before approving.

  3. 03

    How to paste a command

    Copy one command at a time from this page. Click inside the terminal window, paste (Mac: ⌘+V, Windows: Ctrl+V or right-click → Paste), then press Return / Enter. Wait until the prompt comes back before running the next command. You do not need to type the leading $ if you see one in other docs.

  4. 04

    Do not close the installer until verified

    Keep the installer terminal (or admin PowerShell) open until the install finishes without errors. Closing early can leave a half-written binary or an incomplete PATH update — especially on Windows.

  5. 05

    Open a new terminal after installers

    PATH updates often only apply to new shells — especially on Windows. Do not close the install session until the installer finishes, then open a fresh Terminal/PowerShell before running --version checks.

  6. 06

    Inspect before you pipe an installer

    Commands like curl … | bash download and run a script immediately. Prefer the official package manager when offered. If you use a curl installer, you can download the script first, open it in a text editor, then run it — never paste installers from random blogs.

  7. 07

    Install Goose on macOS or Linux

    Paste the stable release installer from the official Goose installation docs (aaif-goose). When it finishes, open a new terminal so ~/.local/bin or the installer’s chosen path is available.

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

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    Goose installation
  8. 08

    Install Goose on Windows (PowerShell)

    Windows

    Official docs download the script first, then run it — do not pipe irm straight into iex. Close and reopen PowerShell afterward. Prefer Git Bash/MSYS2 with the curl installer if that matches your shell.

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

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    Goose installation
  9. 09

    Optional: install the Goose desktop app

    The desktop download is separate from the CLI. Use the official AAIF Goose releases page if you want the graphical session surface; do not assume installing it also puts the CLI on PATH.

    Goose releases
  10. 10

    Verify Goose

    Run the version check in a fresh terminal. A PATH warning means the executable exists but its install directory is not yet searchable.

    bash
    goose --version

    You should see: Goose prints a version number. If the command is missing, open a new terminal and add the installer’s ~/.local/bin path as directed.

    If this fails
    • goose: command not found after installation. Open a new terminal and rerun goose --version. If it still fails, add the installer’s ~/.local/bin directory to PATH or use the manual release binary path from the official guide.
    Goose quickstart

Repository or project

2. Start in the right place

Keep the first repository small, clean, and easy to roll back while you learn the harness’s permissions and context model.

  1. 01

    Enter the practice repository

    Use a clean branch or disposable clone. Keep .env files, cloud credentials, and production data outside the first Goose context.

    bash
    cd path/to/your-repository

    You should see: The prompt shows you are inside the intended folder (check with `pwd`).

    If this fails
    • “No such file or directory” or you are still in your home folder. Create or clone the practice folder first, then `cd` into it before starting the tool.
  2. 02

    Choose a provider and model

    Follow the interactive prompts. Choose a local model if you want the provider data path to stay local, or confirm the hosted provider’s billing and retention terms first.

    bash
    goose configure

    You should see: The command finishes without an error before you continue.

    If this fails
    • The command exits with an error. Read the last few lines of output, fix the named issue, then re-run this step before continuing.
    Goose providers
  3. 03

    Start a session

    Launch the session from the repository root. Goose may be able to run shell commands and extensions, so read each permission prompt before approving it.

    bash
    goose session

    You should see: The tool starts in this folder and waits for your first prompt (or shows a short first-run / sign-in screen).

    If this fails
    • Nothing happens, or you land in the wrong folder. Confirm you are inside the practice repo (`pwd`), that you signed in, and that you opened a new terminal after install.
    Goose quickstart

First run

Explain one repository without edits

Use this task to test the workflow before handing over a larger repository or production responsibility.

  1. 01Use a disposable repository and choose the least-privileged provider and extension set you need.
  2. 02Ask Goose to list the entry points, test command, and likely risky files; explicitly say: do not edit files or run mutating commands.
  3. 03Exit the session, inspect git status, and confirm no secrets or unexpected extension processes were involved.

Why this is safe: The task exercises provider configuration and repository context while keeping the first output reviewable and the working tree easy to restore.

Stop and review if

  • The provider or extension asks for production credentials, broad filesystem access, or an unknown MCP endpoint.
  • Goose edits files or runs destructive commands before you approve the task.
  • You cannot identify which hosted provider will receive the prompt or where its API key is stored.

The operating boundary

Privacy, data, and cost

The setup is incomplete until you know what the harness can see, what account pays for it, and who approves a risky action.

Privacy

Goose is open-source and does not supply the model’s privacy policy. Prompts, selected files, and tool output go to the provider you configure; anonymous Goose usage telemetry is separately configurable and is intended to exclude conversation and code content.

Training on code: tier dependent

Data residency, retention, and training depend on the selected hosted provider; local providers avoid that hosted model path but still require local secrets and extension review.

Sensitive repos: Start with a sanitized clone, keep API keys in the keyring or secrets store rather than config.yaml, disable telemetry if your policy requires it, and allow only trusted extensions.

Pricing

The Goose client is free and open source. Hosted model inference is billed by the provider you choose; local inference is paid through your own hardware or infrastructure instead.

Model: usage based

Watch out: A free install is not free inference. Long tool loops, large context, MCP calls, and cloud model retries can create provider charges outside Goose.

Estimate a seat stack

When setup goes wrong

  • goose: command not found after installation.

    Open a new terminal and rerun goose --version. If it still fails, add the installer’s ~/.local/bin directory to PATH or use the manual release binary path from the official guide.

  • Goose says no provider or API key is configured.

    Run goose configure again, select the intended provider and model, and confirm its key has credits. Provider keys do not belong in config.yaml; check the keyring or documented secrets path.

  • The keyring cannot be accessed.

    Read Goose’s keyring fallback guidance. On a disposable or headless machine, use the documented file-based secret option and protect the resulting secrets file; do not commit it.

  • An extension or MCP tool behaves unexpectedly.

    Stop the session, remove untrusted extensions, and re-enable only the server you can identify. Start Goose again with a smaller extension set and explicit tool approvals.

Next steps

After the first successful run

Keep the pilot small, then compare surfaces and budget before a team rollout.

Compare harnessesBuyer guideOpen-source agents hubAI stack cost calculatorGPU inference (rent)Local GPU sizingBuyer guidesLocal open-source AI guide

Setup details change quickly. The page was checked August 8, 2026; use the official source below before installing in a managed or production environment.

Goose documentationCompare all harnesses