Goose

Goose is Block's open-source coding agent. It supports two ways to point at an OpenAI-compatible endpoint: reuse the built-in openai provider and change the host, or declare a standalone custom provider. The latter is recommended — the endpoint details stay in one place, and it is easier to keep several configurations side by side.

PrerequisitesCopy anchor link

First create a dedicated key for Goose on the console's "API Keys" page (naming it goose makes usage easier to track):

• Console: https://aicentos.com
• Create a key: https://aicentos.com/keys
• Top up when the balance runs out: https://aicentos.com/wallet

Configuration to fill inCopy anchor link

Setup stepsCopy anchor link

1. Set the API Key environment variableCopy anchor link

export AICENTOS_API_KEY="sk-your-API-Key"

Add it to ~/.zshrc or ~/.bashrc to persist it. Do not put the key into config.yaml — the official guidance is to use environment variables or the system keychain.

2. Declare the custom providerCopy anchor link

Create ~/.config/goose/custom_providers/aicentos.json (%APPDATA%\Block\goose\config\custom_providers\ on Windows):

{
  "name": "aicentos",
  "engine": "openai",
  "display_name": "aicentos",
  "description": "Models available through aicentos",
  "api_key_env": "AICENTOS_API_KEY",
  "base_url": "https://aicentos.com/v1/chat/completions",
  "models": [
    {
      "name": "gpt-4o",
      "context_limit": 128000
    }
  ],
  "supports_streaming": true,
  "dynamic_models": true
}

The required fields are name, engine, display_name, base_url and models; engine takes openai / anthropic / ollama.

Model names follow the Model Gallery in the console; see Supported models.

3. Set it as the default in config.yamlCopy anchor link

Edit ~/.config/goose/config.yaml:

GOOSE_PROVIDER: aicentos
GOOSE_MODEL: gpt-4o

At startup Goose scans the custom_providers/ directory and registers them automatically; you can also switch providers in the graphical interface afterwards.

TestCopy anchor link

Verify with a non-interactive session first:

goose run -t "Answer in one sentence: what is 1+1?"

A normal response means the integration works.

NotesCopy anchor link

• base_url must be the full path (including /v1/chat/completions here), unlike how most clients do it. If you need to specify the path explicitly, newer versions also support a base_path field, which takes precedence over URL parsing.
• Environment variables take precedence over config.yaml. If OPENAI_HOST is already exported in your shell, it silently overrides the file configuration; run env | grep -i openai first when troubleshooting.
• Goose only starts properly once a provider is selected. If you wrote the configuration in config.yaml but never ran goose configure, you may see No provider configured — a common misconception, since the configuration itself is YAML format, not .env.
• With dynamic_models: true, Goose calls the endpoint's /v1/models to fetch the model list; if you only want to expose specific models, remove the field or set it to false.
• A simpler alternative is to reuse the built-in provider: set GOOSE_PROVIDER: openai in config.yaml and assemble the endpoint with OPENAI_HOST plus OPENAI_BASE_PATH. This is less work, but couples you more tightly to environment variables and runs into the override problem above.
• Troubleshooting order: does the provider name match the JSON file name exactly → does base_url include the full path → are the environment variables visible → is the balance sufficient.

Related linksCopy anchor link

• Custom Provider documentation: https://block.github.io/goose/docs/api/providers/custom