# Goose

Source: https://docs.aicentos.com/en/clients/goose

Language: en

> Use aicentos in Goose — declare a custom OpenAI-compatible provider

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.

## Prerequisites

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](https://aicentos.com)
* Create a key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Configuration to fill in

| Field                | Value                                              |
| -------------------- | -------------------------------------------------- |
| Custom provider file | `~/.config/goose/custom_providers/aicentos.json`   |
| engine               | `openai`                                           |
| base\_url            | `https://aicentos.com/v1/chat/completions`         |
| api\_key\_env        | `AICENTOS_API_KEY`                                 |
| Model                | A model name from the Model Gallery in the console |

## Setup steps

### 1. Set the API Key environment variable

```bash
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 provider

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

```json
{
  "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](https://docs.aicentos.com/en/billing/models-list).

### 3. Set it as the default in config.yaml

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

```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.

## Test

Verify with a non-interactive session first:

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

A normal response means the integration works.

## Notes

* **`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 links

* Custom Provider documentation: [https://block.github.io/goose/docs/api/providers/custom](https://block.github.io/goose/docs/api/providers/custom)