Connect Goose to uttapen

Run Goose on uttapen: OPENAI_HOST and GOOSE_MODEL, GOOSE_MAX_TOKENS to keep the hold small, and the model families that do not work in Goose today.

Goose is an open-source agent with desktop and terminal apps. The simplest way to point it at uttapen is the built-in openai provider with a different host. This page was checked against the official docs for version 1.51.

Setup with environment variables

export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="anthropic/claude-sonnet-5"
export OPENAI_HOST="https://api.uttapen.ir"
export OPENAI_API_KEY="sk-up-..."
export GOOSE_MAX_TOKENS=8192
export GOOSE_CONTEXT_LIMIT=200000

OPENAI_HOST is the host only, without /v1. The request path comes from OPENAI_BASE_PATH, which defaults to v1/chat/completions — exactly what we serve. If you get a 404, check first that /v1 isn't in the URL twice.
goose configure won't accept an arbitrary model name, so pass our id through GOOSE_MODEL (or ~/.config/goose/config.yaml).
Keep the key in the environment or the keyring; a key written into config.yaml is ignored.

The output ceiling

By default Goose guesses the output ceiling from its bundled catalogue, and for models it recognises that guess can be as high as 128,000 tokens. Since uttapen reserves the cost of that ceiling before sending (pricing), a single request can lock most of your balance and earn you a 402.

Always set GOOSE_MAX_TOKENS (say 8192); it takes priority over the catalogue guess. For models Goose doesn't recognise it sends no ceiling at all, which isn't ideal either: the hold falls back to a default estimate, and if the model writes more, the real amount is still deducted in full.

Which models

In Goose, GPT-5-family and o-series ids (openai/gpt-5-mini, openai/o3 and friends) are routed to the Responses path. uttapen doesn't serve it, so those calls come back as 404 not_found. Until Goose changes that behaviour, use other models in this tool.

Safe and good picks for coding: anthropic/claude-sonnet-5, qwen/qwen3-coder, deepseek/deepseek-v3.2, z-ai/glm-4.7 and moonshotai/kimi-k2.5.

This version of Goose has no separate model for titles or light jobs — everything runs on the main model. To push part of the work onto something cheap, use a dedicated agent or recipe with its own model.

A custom provider (optional)

If you'd rather see uttapen as its own entry instead of replacing the built-in provider, drop a JSON file in ~/.config/goose/custom_providers/ — or use Settings → Models → Configure Providers → Add Custom Provider in the desktop app, or goose configure → Custom Providers in the terminal. The fields are name, engine (openai), display_name, api_key_env, base_url and a models array of name and context_limit entries. Give the host form of the URL, as above, so v1/chat/completions isn't appended twice.

Checking that it works

goose session

Send a short message, then look for the request in Dashboard → Usage.

Troubleshooting

Error	Cause in Goose	Fix
`401 invalid_api_key`	`OPENAI_API_KEY` isn't set, or the key only exists in `config.yaml`, which is ignored	Export it, or store it in the keyring
`404 not_found`	A GPT-5-family or o-series model, or `/v1` doubled in the URL	Pick another model; set `OPENAI_HOST` without `/v1`
`404 model_not_found`	`GOOSE_MODEL` doesn't match a real id	Copy it from /en/models (the `404` also lists the closest ids it guessed, in `uttapen.suggestions`)
`402 insufficient_balance`	An oversized hold because `GOOSE_MAX_TOKENS` wasn't set	Set it, and top up
`429`	The key's rate or monthly limit (rate limits)	Wait, or raise the limit

If your available balance can't cover the full output ceiling, uttapen lowers it to fit (floor 1,024 tokens) and returns the granted number in the X-Uttapen-Max-Tokens header, so a reply may end unfinished. 402 is only for the case where even that floor doesn't fit.

Other tools are in integrations; error codes are in errors.

Goose: environment variables and a custom provider