goose

goose connects to Actualyze over the OpenAI Chat Completions API as a custom provider. You can create the provider in goose Desktop, with goose configure in the CLI, or as a JSON file. A custom provider keeps its own API key, so it doesn't interfere with an OpenAI setup you already have. goose fetches the model list from Actualyze's /models endpoint, so its model picker lists the models your key can call. It doesn't read the context windows in that list, though; see Choose a model. goose is part of the Agentic AI Foundation at the Linux Foundation.

#Before you start

• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission. The key's budget is the one your goose usage draws down.
• At least one model your key can call that supports tool calling. goose relies on tool calling, so models without it don't work. Choose a model shows how to check.

#Install

goose Desktop downloads for macOS, Linux and Windows are on the installation page. On macOS you can also use Homebrew:

brew install --cask block-goose

For the CLI on macOS, Linux, or Windows (in Git Bash), run the install script:

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

The script finishes by running goose configure, where the CLI steps below begin. Homebrew users can run brew install block-goose-cli instead.

#Connect to Actualyze

#In goose Desktop

1. Open the sidebar with the button in the top-left corner, then click Settings.
2. Open the Models tab and click Configure providers.
3. Click the Add Provider card, then Configure manually.
4. Fill in the fields from the table below and click Create Provider.

The form requires at least one entry in Available Models, but goose still lists every model from Actualyze's /models endpoint. The entries only serve as a fallback list for endpoints that have no /models.

goose stores the API key in the system keychain, or in secrets.yaml when the keyring is disabled or unavailable. To start using the provider, go to Settings → Models → Switch models, choose Actualyze, and pick a model.

#With the goose CLI

Run goose configure, choose Custom Providers, then Add A Custom Provider. Answer the prompts with the same values: provider type OpenAI Compatible, the name Actualyze, the API URL above, Yes to authentication with a static API key, at least one model ID, and streaming on. Skip the base path and custom headers.

goose then asks which of the models you entered should be the default, and makes Actualyze the active provider. To pick from Actualyze's full model list later, run goose configure again, choose Configure Providers, and select Actualyze.

#As a config file

goose keeps each custom provider as a JSON file in ~/.config/goose/custom_providers/ (on Windows, %APPDATA%\Block\goose\config\custom_providers\). You can write one yourself:

{
  "name": "actualyze",
  "engine": "openai",
  "display_name": "Actualyze",
  "description": "Actualyze OpenAI-compatible endpoint",
  "api_key_env": "ACTUALYZE_API_KEY",
  "base_url": "https://app.actualyze.ai/openai/v1/chat/completions",
  "models": [{ "name": "<model-id>", "context_limit": 200000 }],
  "supports_streaming": true,
  "requires_auth": true
}

Set the key in the variable that api_key_env names, then start a session with the provider:

export ACTUALYZE_API_KEY="<your-actualyze-api-key>"
goose session --provider actualyze --model <model-id>

• engine: openai makes goose speak the OpenAI Chat Completions API to base_url.
• goose fetches the model list from Actualyze, so models doesn't need every model. Its entries are where you set context windows, and the fallback list for endpoints that have no /models.
• context_limit is the model's context window. The 200000 above is a placeholder; see Choose a model.
• goose Desktop reads provider files when it starts, so restart it after you edit one.

#With the built-in OpenAI provider

If you'd rather not add a provider, goose's built-in OpenAI provider can point at Actualyze through environment variables. This takes over that provider, so use a custom provider if you also call OpenAI directly.

export OPENAI_HOST="https://app.actualyze.ai"
export OPENAI_BASE_PATH="openai/v1/chat/completions"
export OPENAI_API_KEY="<your-actualyze-api-key>"
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="<model-id>"
export GOOSE_CONTEXT_LIMIT=200000

• OPENAI_HOST is the origin only, with no path. OPENAI_BASE_PATH is the request path goose appends to it.
• goose fetches the model list from Actualyze with these settings too, so you can also pick the model in goose configure (Configure Providers, then OpenAI) instead of setting GOOSE_MODEL.
• GOOSE_CONTEXT_LIMIT sets the main model's context window. The 200000 above is a placeholder.

#Choose a model

Model names are catalog model IDs or Virtual Model slugs, written exactly as Actualyze lists them, without adding a provider/ prefix of your own. goose's model pickers list them from Actualyze's /models endpoint. To check a model's details yourself, ask the endpoint:

curl https://app.actualyze.ai/openai/v1/models \
  -H "Authorization: Bearer <your-actualyze-api-key>"

Each entry carries context_window, max_output_tokens and a capabilities object that includes tool_use. The Model Catalog in the Actualyze app shows the same details.

goose doesn't read context_window from the listing. It recognizes many model names from its own catalog and uses the context window it has on record for them. For any other name, Virtual Model slugs included, it assumes 128,000 tokens. To give goose the real window, use either of these:

• In the provider file, add the model to models with context_limit set to its context_window. Providers you create in Desktop or the CLI have a file too: custom_actualyze.json in the same directory.
• Set GOOSE_CONTEXT_LIMIT, which overrides the main model's window with any provider.

#Troubleshooting

• 404 with the built-in OpenAI provider: OPENAI_BASE_PATH is wrong. With OPENAI_HOST set to https://app.actualyze.ai, it must be openai/v1/chat/completions.
• goose reports a missing ACTUALYZE_API_KEY when it starts: the variable named in api_key_env isn't set. A key in config.yaml doesn't count, because goose ignores it.
• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401 otherwise: the key was rejected. It may be mistyped, revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.
• Model not found: the model name doesn't match a catalog model or Virtual Model your workspace serves.
• A model is missing from goose's picker: the picker shows what /openai/v1/models returns for your key, minus models goose's catalog marks as lacking tool calling. Compare with the curl output above.

#Reference

Requests you cancel mid-stream still draw down the usage they consumed.

For goose's own settings, see its documentation on providers, configuration files and environment variables.