aider: setup through environment variables

aider is a terminal tool, and instead of a settings UI it uses environment variables plus a --model flag. That works well with the gateway: the same pair of variables decides whether a request goes to Claude or to an OpenAI-compatible model.

Two variable sets

Under the hood aider relies on a library that reads a provider prefix from the model name (anthropic/..., openai/...), and the prefix decides which variable pair it reads.

For Anthropic mode:

export ANTHROPIC_API_KEY="fetch_your_key"
export ANTHROPIC_API_BASE="https://api.zukko.pro"

For OpenAI-compatible mode:

export OPENAI_API_KEY="fetch_your_key"
export OPENAI_API_BASE="https://api.zukko.pro/v1"

Note the base URL difference — same rule as everywhere else: the Anthropic path has no /v1, the OpenAI-compatible one does. Mix them up and you get the same 404 as in any other client, just without a visible settings screen where the mistake would stand out.

Running with a specific model

The model is then given with the prefix on the flag:

aider --model anthropic/claude-sonnet-5

aider --model openai/gpt-5.6-sol

aider --model openai/glm-5.3

aider --model openai/glm-5.3-flash

The openai/ prefix here does not mean the model comes from OpenAI — it only signals the request format (OpenAI Chat Completions), which the gateway understands the same way for GPT and GLM, since all of them are OpenAI-compatible on our side (and for Claude too — the gateway converts the format). The id after the slash must match the catalogue exactly: claude-opus-5-5, claude-sonnet-5, gpt-5.6-sol, gpt-5.6-luna, glm-5.3, glm-5.3-flash (current list: GET https://api.zukko.pro/v1/models).

If the variables don't get picked up

aider reads the environment of whichever shell launches it. A common reason settings "don't work" is that the variables were exported in one terminal while aider runs from another, or from a script with a clean environment. Confirm the process actually sees it:

env | grep -i api_key

If you use a project .env file, aider picks it up automatically when started from the project directory — nothing extra to wire up — but variables from .env don't override ones already exported in the shell; the shell wins on conflict.

Checking the key separately from aider

Before chasing why aider specifically isn't working, confirm the key and address work on their own:

curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"test"}]}'

If curl answers fine and aider doesn't, the issue is in what environment the aider process actually sees, not in the key.

Common errors and what they mean

• 401 authentication_error — the key never reached the header; check that the variable was actually exported (export, not a plain assignment — without export the aider child process never sees it).
• 402 insufficient_balance — the balance is at zero, the request never reached a model, so nothing was wasted.
• 404 model_not_found — either a wrong id after the slash, or ANTHROPIC_API_BASE/OPENAI_API_BASE got swapped.
• 400 model_retired — the error text names the current id to use instead; update the --model flag.
• 503 model_disabled — the model is disabled in the catalogue; pick another one from /v1/models.
• 429 with key_daily_limit_reached — the key has a daily spending cap set in the dashboard and it's been hit (it resets at 00:00 UTC; the gateway has no general rate limit, so a 429 without this code comes from the model provider); limits and allowed models are configured on the key's page under /app/api-keys.

Idempotency and retries

If you're wrapping aider in your own scripts with retries, add an Idempotency-Key header with a unique value per logical request (kept the same across its retries) — repeating it with the same key within 24 hours returns the same response without charging again. Useful for CI, where a step might retry after a network blip but shouldn't be billed twice.

Checking limits and pricing before picking a model

Before hardcoding a specific model into aider launch scripts, it's worth checking current limits and pricing — they live at GET /v1/models/info, no key needed:

curl https://api.zukko.pro/v1/models/info | jq '.data[] | select(.id=="claude-sonnet-5")'

Same catalogue as GET /v1/models, but with pricing and limits per model — useful if you're writing a wrapper around aider that picks a model based on task budget.

Spend history if aider shares a key with other tools

When the same key sits in aider and, say, in CI scripts, it's worth periodically checking overall spend via /v1/usage with cursor pagination — the history covers the whole account (all keys together, no per-key filter):

curl "https://api.zukko.pro/v1/usage?limit=50" \
  -H "Authorization: Bearer fetch_your_key"

If the totals look unexpectedly high while aider's own terminal traffic looked modest, some of that spend likely comes from another process on the same account — worth splitting keys per tool and giving each its own daily cap in the dashboard, so one tool's overspend hits its own limit.

Keys and money

Keys are created at https://zukko.pro/app/api-keys and shown once — save it straight into a secrets manager or your shell profile's environment variables, not into terminal history. Top up via SBP, card through PayPear, or crypto; foreign Mastercard EU cards have been supported through Fride since 2026-09-16 (about 13% fee, amounts $2–$594); the minimum top-up is $1. There's no starting balance; from zero, link Telegram in the dashboard, subscribe to @zukkopro↗, and press "Check" — that gives a one-time $0.50.