Skip to main content
Goose is Block’s open-source, on-machine coding agent. Goose doesn’t have a built-in Tokios provider, but it supports custom providers through a JSON file, so you can point it at https://api.tokios.com/v1 and reach any model behind your connector.

​
Prerequisites

  • A running Tokios connector paired with your local model — see Connector install
  • A registered model deployment name — see Register a model
  • A Tokios API key (sk-tok-…) — see API keys
  • Goose installed

​
Configure a custom provider

Create a custom provider file for Goose. Custom-provider config has changed across Goose releases, so confirm the exact JSON schema (field names, required vs. optional keys, and whether a models array or a different structure is expected) against your installed version.
Create a JSON file in ~/.config/goose/custom_providers/:
tokios.json
The file names an environment variable rather than holding the key itself, so export it before starting Goose:
Replace gemma-tunnel with the public deployment name you registered on the Models tab — not the local model id your backend (Ollama, llama.cpp, vLLM, or LM Studio) uses. Because api_key_env stores only the variable name, this file is safe to commit; the key never enters it.
If requests 404, check how your Goose release interprets base_url. Goose’s own custom-provider example writes the full endpoint path (.../v1/chat/completions) rather than just the /v1 root, and the two forms are not interchangeable — try https://api.tokios.com/v1/chat/completions if https://api.tokios.com/v1 fails.

​
Alternative: the built-in OpenAI provider

If you’d rather not add a provider file, Goose’s built-in openai provider accepts a custom host. Goose persists these to ~/.config/goose/config.yaml:
OPENAI_HOST is the host root and OPENAI_BASE_PATH is the request path, which defaults to v1/chat/completions — the path Tokios serves, so you normally leave it unset.

​
Alternative: environment variable

Instead of a custom provider file, you can point Goose’s OpenAI-compatible client at Tokios with the OPENAI_HOST environment variable. Confirm against your installed version whether OPENAI_HOST expects the bare host or the full /v1 path, and whether it requires pairing with OPENAI_API_KEY for authentication.
Goose treats Anthropic as a separate first-party provider, and a generic custom Anthropic base URL isn’t available yet (tracked as an open feature request: block/goose#3777). Use the OpenAI-compatible provider slot above to reach Tokios.

​
Pick a tool-capable model

Goose’s agent relies on tool calling to read files, run commands, and edit code. Not every local model handles tool calls reliably — pick a deployment backed by a model with strong tool-calling support before you rely on Goose for real edits. See Choose a model by task for guidance on matching a model to agentic coding work.

​
Troubleshooting

The API key Goose sent is missing, malformed, or has been revoked. Confirm api_key (or OPENAI_API_KEY) holds the full sk-tok-… key with no extra whitespace, and check its status on the Keys tab.
The model name in models doesn’t match a registered deployment. Confirm it exactly matches the public name on the Models tab — not your Ollama, llama.cpp, vLLM, or LM Studio local model id.
The connector for that deployment is offline or at its concurrency cap. Check the Connectors tab — the connector needs to show as Online, and the machine running it needs to still be up and reachable.

​
Next steps

Quickstart

Set up your connector, register a model, and create an API key from scratch.

Choose a model by task

Match a local model to agentic coding work before you wire it into Goose.