Aider

Aider talks to Actualyze over the OpenAI Chat Completions API, through its client for OpenAI-compatible endpoints. You give it the base URL and your Actualyze API key, and name the model with an openai/ prefix. Aider doesn't discover models from Actualyze: it never calls the /models endpoint, so it doesn't see the model list or the context windows it carries. You choose the model ID yourself, and you can give Aider the model's limits in a small metadata file.

#Before you start

• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission. The key's budget is the one your Aider usage draws down.
• The ID of a model your key can call: a catalog model ID or a Virtual Model slug. Choose a model shows how to list them.

#Install

If Aider isn't installed yet, Aider's installer sets it up in its own Python environment:

python -m pip install aider-install
aider-install

Aider's installation guide covers the one-line installers for macOS, Linux and Windows, and installs with uv or pipx.

#Connect to Actualyze

Add these lines to your shell profile, then open a new terminal:

export OPENAI_API_BASE="https://app.actualyze.ai/openai/v1"
export OPENAI_API_KEY="<your-actualyze-api-key>"

Then start Aider in your project with a model your key can call:

cd /path/to/your/project
aider --model openai/<model-id>

• OPENAI_API_BASE is the OpenAI-compatible endpoint. Keep the trailing /openai/v1: Aider appends /chat/completions itself.
• OPENAI_API_KEY carries your Actualyze API key.
• On Windows, set both with setx OPENAI_API_BASE … and setx OPENAI_API_KEY …, then restart the shell.

Other tools in the same shell read OPENAI_API_KEY too. If one of them should use a different key, put the settings in Aider's config file instead.

#In a config file

Aider reads .aider.conf.yml from your home directory, the root of your git repo, and the current directory, in that order. Later files win.

model: openai/<model-id>
openai-api-base: https://app.actualyze.ai/openai/v1
openai-api-key: <your-actualyze-api-key>

With model set here, aider alone starts on that model.

#Choose a model

Put a catalog model ID or Virtual Model slug after openai/. The prefix tells Aider which client to use; the ID itself is what reaches Actualyze. Aider's /models command and --list-models option search the model list Aider takes from LiteLLM, not Actualyze. To see the models your key can call, ask the endpoint:

curl https://app.actualyze.ai/openai/v1/models \
  -H "Authorization: Bearer <your-actualyze-api-key>"

Each entry carries context_window and max_output_tokens (null when the catalog has no value). Aider doesn't read these fields. The Model Catalog in the Actualyze app shows the same limits.

#Register the context window

Aider takes model limits from LiteLLM's model list. That list covers OpenAI model IDs, so openai/ followed by an OpenAI model ID already has limits. For any other ID, Virtual Model slugs included, Aider warns at startup that it doesn't know the model's context window or costs. Requests still work, but Aider then sizes its own context small: it summarizes chat history once it passes 1,024 tokens and gives the repository map 1,024 tokens. With the context window registered, both scale up with it, and Aider warns you before sending a chat that won't fit. To give Aider the model's real limits, create .aider.model.metadata.json in your home directory, your repo root or the current directory, or pass a file with --model-metadata-file:

{
  "openai/<model-id>": {
    "max_tokens": 64000,
    "max_input_tokens": 200000,
    "max_output_tokens": 64000,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}

• The key is the same openai/<model-id> you pass to --model. Its prefix must match litellm_provider.
• The numbers above are placeholders. Copy max_input_tokens from the model's context_window, and max_output_tokens and max_tokens from its max_output_tokens.
• Leave out the cost fields. Actualyze meters each request against the key's budget either way.

#Model settings

Aider picks edit settings by model name. An ID that contains a model family Aider knows gets that family's settings. Any other ID, such as a Virtual Model slug, gets the whole edit format, where the model rewrites the entire file for every change, and no repository map. For a capable coding model, override both in .aider.model.settings.yml, which Aider looks for in the same three places:

- name: openai/<model-id>
  edit_format: diff
  use_repo_map: true

#Troubleshooting

• A warning about unknown context window size and costs: Aider has no metadata for the model. Register it as shown above.
• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401: the key was rejected. It may be mistyped, revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.
• Every request fails right after setup: check the base URL. It must end in /openai/v1.
• 401 or failed requests even though your shell profile is right: Aider loads .env files from your home directory, the repo root and the current directory, and an OPENAI_API_KEY or OPENAI_API_BASE in one of them replaces your shell's value. Remove it there, or set openai-api-key and openai-api-base in .aider.conf.yml, which Aider applies after .env files.
• Model not found: the ID after openai/ doesn't match a catalog model or Virtual Model your workspace serves.

#Reference

Requests you cancel mid-stream still draw down the usage they consumed.

For Aider's own settings, see its documentation on OpenAI-compatible APIs, the YAML config file and advanced model settings.