Install goose | goose | Your open source AI agent (original) (raw)

Choose to install the Desktop and/or CLI version of goose:

Install goose Desktop directly from the browser or with Homebrew.

Option 1: Install via Download

  1. Unzip the downloaded zip file.
  2. Run the executable file to launch the goose Desktop application.

Option 2: Install via Homebrew

Homebrew downloads the same app but can take care of updates too.

  brew install --cask block-goose

Permissions

If you're on an Apple Mac M3 and the goose Desktop app shows no window on launch, check and update the following:

Ensure the ~/.config directory has read and write access.

goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the Known Issues Guide

Set LLM Provider​

goose works with supported LLM providers that give goose the AI intelligence it needs to understand your requests. On first use, you'll be prompted to configure your preferred provider.

On the welcome screen the first time you open goose, choose how to configure a provider:

tip

goose relies heavily on tool calling capabilities and currently works best with Claude 4 models.

Free Credits Offer

You'll receive $10 in free credits the first time you automatically authenticate with Tetrate through goose. This offer is available to both new and existing Tetrate users.

Update Provider​

You can change your LLM provider and/or model or update your API key at any time.

  1. Click the button in the top-left to open the sidebar.
  2. Click the Settings button on the sidebar.
  3. Click the Models tab.
  4. Choose to update your provider, switch models, or click Reset Provider and Model to clear your settings and return to the welcome screen. See details about these configuration options.

Billing

Google Gemini

offers a free tier you can get started with. Otherwise, you'll need to ensure that you have credits available in your LLM Provider account to successfully make requests.

Some providers also have rate limits on API usage, which can affect your experience. Check out our

Handling Rate Limits

guide to learn how to efficiently manage these limits while using goose.

Running goose​

Starting a session in the goose Desktop is straightforward. After choosing your provider, you'll see the session interface ready for use.

Type your questions, tasks, or instructions directly into the input field, and goose will get to work immediately.

The goose CLI and Desktop UI share all core configurations, including LLM provider settings, model selection, and extension configurations. When you install or configure extensions in either interface, the settings are stored in a central location, making them available to both the Desktop application and CLI. This makes it convenient to switch between interfaces while maintaining consistent settings. For more information, visit the Config Files guide.

info

While core configurations are shared between interfaces, extensions have flexibility in how they store authentication credentials. Some extensions may use the shared config files while others implement their own storage methods.

Navigate to shared configurations through:

  1. Click the button in the top-left to open the sidebar.
  2. Click the Settings button on the sidebar.

Pin a goose version in CI/CD​

In CI/CD (and other automated, non-interactive environments), pin a specific version with GOOSE_VERSION to make installs reproducible and avoid 404s when downloading the goose CLI binary assets if the stable release tag doesn’t include them.

See CI/CD Environments for a complete example and usage details.

Generate manpages for Linux distributions​

If you're packaging goose for a Linux distribution or creating a custom build, you can generate Unix manpages from the CLI command definitions:

This creates ROFF-formatted manpages in target/man/ (e.g., goose.1, goose-session.1) that can be installed to /usr/share/man/man1/ to provide offline documentation via the man command.

Manpage generation requires the goose source repository and is intended for distribution packagers preparing packages for Fedora, Debian, and other Linux distributions. See the generate_manpages.rs source for implementation details.

Additional Resources​

You can also configure Extensions to extend goose's functionality, including adding new ones or toggling them on and off. For detailed instructions, visit the Using Extensions Guide.