Goose

Goose is an open-source AI agent that runs on your machine as a CLI and a desktop app; the project now lives at aaif-goose/goose (formerly block/goose). It connects to Tokens as a custom provider with the openai engine, which sends chat completions to https://tokens.bd/v1/chat/completions.

The Tokens CLI doesn't configure Goose. Use Goose's own wizard or drop a provider file in place.

Install Goose#

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
# or with Homebrew
brew install block-goose-cli          # CLI
brew install --cask block-goose       # desktop app

Create a key at /dashboard/keys. API keys explains spend caps and allow-lists.

Option A: goose configure#

1. Run goose configure.
2. Choose Custom Providers, then Add A Custom Provider.
3. Fill in the prompts:

Goose stores the key in your system keychain, or in secrets.yaml if no keychain is available. In the desktop app the same form is under Settings > Add Custom Provider.

Note the API URL: Goose's custom providers take the full chat completions path, not just /v1.

Option B: a provider file#

Create ~/.config/goose/custom_providers/tokens.json. On Windows the folder is %APPDATA%\Block\goose\config\custom_providers\.

{
  "name": "tokens",
  "engine": "openai",
  "display_name": "Tokens",
  "description": "Tokens AI gateway",
  "api_key_env": "TOKENS_API_KEY",
  "base_url": "https://tokens.bd/v1/chat/completions",
  "models": [{ "name": "deepseek/deepseek-v4.1-flash", "context_limit": 128000 }],
  "supports_streaming": true,
  "requires_auth": true
}

context_limit is a placeholder; copy the real context window from the model's page in /models. The file has no secret in it, because api_key_env tells Goose to read TOKENS_API_KEY:

export TOKENS_API_KEY="tok_live_your_key"
goose session start --provider tokens

$env:TOKENS_API_KEY = "tok_live_your_key"   # this window
setx TOKENS_API_KEY "tok_live_your_key"     # new windows
goose session start --provider tokens

Option C: the built-in OpenAI provider#

If you'd rather not add a custom provider, Goose's built-in OpenAI provider can point at Tokens. Set these as environment variables (export in bash, $env: in PowerShell):

GOOSE_PROVIDER=openai
OPENAI_HOST=https://tokens.bd
OPENAI_BASE_PATH=v1/chat/completions
OPENAI_API_KEY=tok_live_your_key
GOOSE_MODEL=deepseek/deepseek-v4.1-flash

OPENAI_HOST is the bare host with no path; the path goes in OPENAI_BASE_PATH. This takes over Goose's OpenAI provider, so if you also use OpenAI directly through Goose, Option B is cleaner.

Switch models#

For a custom provider, add more entries to the models array (or to "Available Models" in the wizard) with exact ids from /models or GET /v1/models, each with its own context_limit. Then pick the model in the desktop app's model picker, or set GOOSE_MODEL for the CLI.

With the built-in OpenAI provider, goose configure won't accept a custom model name. Set GOOSE_MODEL, or edit the providers: block in ~/.config/goose/config.yaml, instead. Choosing a model helps with the choice.

Verify it works#

goose session start --provider tokens

Ask something small, such as "list the files in this folder". The answer should arrive and the request should appear in Usage analytics on the dashboard. In the desktop app, Tokens shows up in the model picker.

To rule out Goose, call the endpoint directly:

curl https://tokens.bd/v1/chat/completions \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "messages": [{"role": "user", "content": "Reply with OK"}], "max_tokens": 10}'

Troubleshooting#

No api key passed in. Goose ignores API keys written into config.yaml. Use the keychain (through goose configure), secrets.yaml, or the environment variable named in api_key_env.

404 on every request. With a custom provider, base_url must be the full https://tokens.bd/v1/chat/completions. With the built-in provider, OPENAI_HOST must be just https://tokens.bd and OPENAI_BASE_PATH must be v1/chat/completions; a wrong base path is the usual cause.

404 model_not_found or 403 model_not_allowed_on_key. The model id is misspelled, or the key's allow-list doesn't include it. Allow-lists can't be edited, so create a new key if needed.

The agent can't use tools. Goose relies on tool calling. If a model doesn't handle tool calls well, switch to another one.

Long sessions fail. Set context_limit to the model's real window so Goose knows how much room it has.

For 402 and 429 errors, see Troubleshooting.