goose Custom Provider Setup

goose documents three ways to create a Custom Provider: Desktop, CLI, and a provider file. TokenHub uses OpenAI Compatible. In goose's custom-provider schema, enter the full Chat Completions URL: https://us-api.tokenhub.com/v1/chat/completions.

Use the official goose Desktop path

1. Click the sidebar button in the upper-left corner.
2. Go to Settings → Models.
3. Click Configure providers.
4. Scroll to the bottom and click Add Custom Provider.
5. Choose OpenAI Compatible for Provider Type.
6. Enter TokenHub for Display Name.
7. Enter https://us-api.tokenhub.com/v1/chat/completions for API URL.
8. Keep This provider requires an API key enabled and enter your TokenHub API key. Desktop stores it in the system keychain, or in secrets.yaml when a keyring is unavailable.
9. Under Available Models, enter exact TokenHub model IDs separated by English commas.
10. Enable Streaming Support and click Create Provider.

Desktop cannot currently add custom headers. If a deployment requires one, create the provider and edit its JSON afterward.

Use the official goose CLI path

Run:

goose configure

Then follow the menu exactly:

1. Select Custom Providers (Add custom provider with compatible API).
2. Select Add A Custom Provider.
3. Choose OpenAI Compatible for API Type.
4. Name it TokenHub and enter the full Chat Completions URL.
5. Answer Yes to Authentication Required, choose Static API key, and paste the TokenHub key.
6. Enter the exact model IDs as a comma-separated list under Available Models.
7. Enable Streaming Support. Add Custom Headers only if the endpoint actually requires them.

The CLI also supports Command (refreshable) for short-lived credentials. A normal TokenHub API key does not need that path.

Inspect the provider file goose generated

On macOS and Linux, files are under ~/.config/goose/custom_providers/. On Windows, use %APPDATA%\Block\goose\config\custom_providers\. The important fields should match:

{
  "name": "tokenhub",
  "engine": "openai",
  "display_name": "TokenHub",
  "api_key_env": "TOKENHUB_API_KEY",
  "base_url": "__API_BASE_URL__/v1/chat/completions",
  "models": [
    {
      "name": "YOUR_TOKENHUB_MODEL_ID",
      "context_limit": 128000
    }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

api_key_env is needed when you hand-write JSON. A static key entered through Desktop or CLI is stored securely by goose. Replace context_limit with the model's real limit.

Switch models and apply the change

In Desktop, go to Settings → Models → Switch models, choose the TokenHub provider and model, and click Select model. The goose documentation says a Custom Provider change takes effect in the next goose session, so do not test it in an old session.

Begin the new session with a read-only coding task and confirm the complete /v1/chat/completions path in TokenHub logs. For a 404, inspect API URL. If a model is invisible, check the comma-separated list or models[].name. If chat works but the agent cannot act, use a model that returns structured tool calls.

Official reference

• goose: Configure an LLM Provider