Installing goose and Configuring a Custom Provider

goose is a general-purpose AI assistant that runs on your computer. In addition to coding, it can handle research, writing, automation, and data organization. You can use it through the desktop app, terminal, or API, and the desktop and terminal versions share the same model configuration. It is suitable for repetitive coding tasks and can also connect to GitHub, databases, and files.

Before you start

goose offers two installation options: Desktop and CLI. Desktop is the graphical version with a window, while CLI is used by entering commands in a terminal. Both share the same core configuration, including the Provider and model. A Provider is the connection configuration that tells goose which model service to use.

Want a window

goose Desktop

• Download the zip on macOS
• Or use brew cask
• Use the installer package on Linux

Terminal only

goose CLI

• download_cli.sh
• Or the Homebrew CLI
• Then run goose session

Windows

Choose an environment first

• Git Bash or MSYS2
• You can also use PowerShell
• If the command is not found, add it to PATH

Before starting, have the model ID from the current model list ready. A model ID is the name the model service uses to identify a specific model, and you must copy the complete ID when using it.

Install and launch for the first time

If you want a graphical window

There are two documented installation methods for macOS:

• Download it from the installation page. The page provides macOS Silicon and macOS Intel versions. After downloading, extract the zip file and run the application inside.
• Alternatively, use Homebrew:

brew install --cask block-goose

This downloads the same application and can also handle updates.

If you are using an Apple Mac M3 and no window appears after opening the app, check whether ~/.config is readable and writable. goose uses this directory to write logs.

For the Linux desktop version, download it from the installation page. The available packages are DEB for Ubuntu/Debian, RPM for RHEL/Fedora, and Flatpak. On Debian or Ubuntu, download the DEB file, open the directory where it was saved, run sudo dpkg -i (filename).deb, and then open goose from the application menu. Replace (filename) with the actual file name.

For the Windows desktop version, download it from the installation page, extract the zip file, and run the application inside.

If you only want the terminal version

On macOS and Linux, run:

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

To skip interactive configuration during installation, add CONFIGURE=false before bash:

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

On macOS, you can also run:

brew install block-goose-cli

To update an installed CLI, run:

goose update

On Windows, one of the following three environments is required: Git Bash, which is included with Git for Windows and marked as recommended; MSYS2; or PowerShell included with Windows 10/11. In Git Bash and MSYS2, use the same download_cli.sh command shown above. In PowerShell, download the script first and then run it:

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

If you are told that goose is not in PATH, follow the installation page and add ~/.local/bin or %USERPROFILE%\.local\bin to the current shell configuration, then reopen the terminal. PATH is a set of directories that the terminal searches for programs. If the installation directory is not included, you may be unable to run an installed program by entering its name directly.

As of 2026-10-09, the CLI version was 1.54.0. By default, the installation script places the program in ~/.local/bin. You can change this directory with the GOOSE_BIN_DIR environment variable. If you change it, the script will not automatically update the shell configuration, and the terminal will report that the directory is not in PATH. Add that directory to PATH or run goose using its full path.

The first time you use goose, it will ask you to configure a Provider. You can skip the built-in providers and add a custom Provider as described in the next section. In the terminal, navigate to the directory where you want to work and run:

goose session

Get connection values from OmniProxy

Prepare the address, key, and model name from your own OmniProxy instance. The custom Provider example uses a base_url ending in /v1/chat/completions, so this guide follows the same format:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   Copy from the current OmniProxy model list; separate multiple models with commas

Copy the complete model name from the current OmniProxy list, including any slashes. As of 2026-10-09, two reference IDs in the provider documentation were grok-4.7 for Grok and gpt-6-luna from the OpenAI documentation. gpt-6-luna supports Chat Completions; function calling in Chat Completions is supported only when reasoning_effort is set to none. Do not copy a name that does not appear in the list.

Enter the tool configuration

A custom Provider can use an OpenAI-, Anthropic-, or Ollama-compatible format. A compatible format means that the tool sends requests according to a common API specification. When connecting to OmniProxy, select OpenAI Compatible.

Desktop

1. Click the button in the upper-left corner to open the sidebar.
2. Click Settings.
3. Click Models.
4. Click Configure providers.
5. Click Add Custom Provider at the bottom of the window.
6. For Provider Type, select OpenAI Compatible. You can set Display Name to OmniProxy. Enter the address from the previous section in API URL. If a key is required, select the option requiring an API Key and enter your OmniProxy key. In Available Models, enter the model names, separating multiple names with commas.
7. Click Create Provider.

The desktop version currently cannot define custom request headers in this window. If you need request headers, edit the configuration file after creating the Provider.

Terminal

Run:

goose configure

Select Custom Providers, then select Add A Custom Provider. For API Type, select OpenAI Compatible, then follow the prompts to enter the name, API URL, whether a key is required, model names, and whether streaming responses are supported.

When configuring manually on Windows, if the keychain reports an error, the installation instructions say to decline saving the key in the keyring and use an environment variable instead. Then run goose configure again. The keychain is a small secure storage system used by the operating system to store secrets.

Configuration file

The documented directories are:

• macOS and Linux: ~/.config/goose/custom_providers/
• Windows: %APPDATA%\Block\goose\config\custom_providers\

You can base the file on the provided example. Replace the name, address, and models with your own values. Store the key in the environment variable specified by api_key_env; do not write the real key into the file:

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Keep a numeric value for context_limit, as shown in the example. The actual context limit depends on the model and OmniProxy; do not treat the example number as the model’s official limit. Before using it, run:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

After entering the working directory, run:

goose session --provider omniproxy --model grok-4.7

Replace the value of --model with the complete ID from the list. goose session does not have a start subcommand. You can also set --provider and --model through the GOOSE_PROVIDER and GOOSE_MODEL environment variables. Even if the gateway does not validate keys, OMNIPROXY_API_KEY must still have a value. It can be a placeholder string used only on your local computer. This configuration successfully read a file in testing on 2026-10-09.

Window

Settings

• Settings in the sidebar
• Models page
• Add Custom Provider

Terminal

goose configure

• Select Custom Providers
• Then select add
• Choose OpenAI Compatible as the type

File

custom_providers

• On macOS and Linux, it is under ~/.config
• On Windows, it is under APPDATA
• Set base_url according to the official example

Verify with a real task

Open a directory containing a regular file and run goose session as shown in the previous section. Ask it to read the first line of a file you specify. It should return the file contents rather than only saying that the configuration was saved.

To read files or execute commands, the session needs the Developer extension. The Developer extension is a tool module that lets goose work with local files and commands. It is generally included in the default configuration. If goose says that it has no file tools, add the following to the command:

--with-builtin developer

Do not also add --no-profile, because that option disables the default extensions.

In testing on 2026-10-09, goose 1.54.0 successfully read the first line of the specified file. The first response may take around one minute.

Then check the OmniProxy request logs to confirm the source and model name.

Launch

A session opens

• goose session
• Provider is the one just added
• The model name is in the list

Task

It actually completed the task

• For example, list the current directory
• Review its response
• Do not rely only on a successful save

Logs

Visible in the gateway

• Use the address from the documentation example
• Do not put the key in the repository
• The model ID matches the list

Common errors

• The goose command cannot be found: Add the installation directory to PATH as described on the installation page, then reopen the terminal.
• No window appears in the desktop version on an M3 Mac: Check read and write permissions for ~/.config.
• The keychain fails: Do not save the key in the keyring; use an environment variable instead.
• The model is not in the list: In the desktop version, select Use custom model and enter the model name manually. goose configure cannot accept a custom model name. For terminal use, switch to the desktop version or edit GOOSE_MODEL directly in the configuration.
• The address cannot be reached: Confirm that the API URL ends in /v1/chat/completions, as in the example, and that OmniProxy is running.
• It says it cannot read files: Add the Developer extension and do not use --no-profile.
• It returns unsupported Responses role: system: The address is usually correct. Switch to another complete ID from the model list.

Official references

For installation, see Install goose. For custom Providers, see goose providers. For the model IDs used in the examples, see the xAI models page and GPT-6 Luna.

Replace every placeholder with values from your own OmniProxy configuration. Never publish a real key.

A saved result or HTTP 200 alone does not prove full Agent compatibility. Check the source and model in OmniProxy's call record.

Official sources · goose ↗