How to use Darkbloom with Aider

At a glance

How do I use Aider with Darkbloom?

Set OPENAI_API_BASE to https://api.darkbloom.dev/v1, set OPENAI_API_KEY to your Darkbloom key, and start Aider with --model openai/<model-id>. It takes about five minutes.

1. Get a Darkbloom API key. Open the Darkbloom console and sign in, add credits (the minimum is $0.50, and Darkbloom says credits are non-refundable and never expire), then choose API console in the console’s left menu and Create API key (Darkbloom’s docs call this page Settings → API Keys). The console shows the key only once, so copy it right away. Every key spends from your prepaid balance, so add only what you are willing to spend while you test, and watch the first sessions, because a coding agent can loop.
2. Install Aider. This is the install command from Aider’s docs:

   Copy

   python -m pip install aider-install
   aider-install

3. Point Aider at Darkbloom. Set two environment variables. On macOS or Linux:

   macOS and LinuxCopy

   export OPENAI_API_BASE="https://api.darkbloom.dev/v1"
   export OPENAI_API_KEY="YOUR_DARKBLOOM_API_KEY"

   Windows (then open a new terminal)Copy

   setx OPENAI_API_BASE "https://api.darkbloom.dev/v1"
   setx OPENAI_API_KEY "YOUR_DARKBLOOM_API_KEY"

4. See which models you can use. Darkbloom’s model list gives each ID with its context window and prices:

   Copy

   curl -s https://api.darkbloom.dev/v1/models \
     -H "Authorization: Bearer $OPENAI_API_KEY"

5. Start Aider in your project with an ID from that list, plus the openai/ prefix:

   Copy

   cd /path/to/your/project
   aider --model openai/gemma-4-26b

Which Darkbloom model should I use with Aider?

Use any ID that GET /v1/models returns. On October 23, 2026 it listed 12 models, shown here from the cheapest output price up, in US dollars per million tokens. Check the live prices before you rely on a number; that public list also names models that are not online. A key can be limited to some models, and Darkbloom refuses any other with a 403 (see the errors table).

None of these models has a score on Aider’s public leaderboard (checked October 22, 2026), so there is no published ranking to follow. For scale, the best entry on that leaderboard, gpt-5 (high), scores 88.0% on Aider’s polyglot coding test, while gpt-oss-120b (high) scores 41.8% and gemma-3-27b-it scores 4.9%. Its newest results date from October 2025. Start with a small, well-defined edit and compare two models on your own code before you rely on one.

How much does Aider cost on Darkbloom?

Darkbloom bills per token from a prepaid balance, so the cost follows how much code and chat Aider sends. A session that sends 200,000 tokens in and gets 20,000 tokens back costs about $0.0054 on gpt-oss-20b and about $0.0128 on gemma-4-26b at the October 23, 2026 prices. The formula is (input tokens × input price + output tokens × output price) ÷ 1,000,000. Darkbloom charges at least $0.0001 per request, so many tiny requests cost more than the formula says. We saw this on October 22, 2026: two Aider requests worth about $0.00004 and $0.00002 at list prices were each billed $0.0001.

In our test run, adding one docstring to a one-file repo with openai/gemma-4-26b took two requests (the edit, then Aider’s commit message) and cost $0.0002 in total.

If a request has no max_tokens, Darkbloom adds 8192 (Darkbloom docs). Aider does not send one, so a single reply is capped at 8,192 tokens, which a rewritten large file can exceed. To raise the cap, create .aider.model.settings.yml in your project. Darkbloom reserves balance for the full max_tokens up front, so a high cap needs a larger balance.

- name: openai/gemma-4-26b
  extra_params:
    max_tokens: 16000

What do Aider’s model warnings mean?

Aider’s warning that the model has an unknown context window size and costs is harmless. At startup Aider prints “Warning for openai/gemma-4-26b: Unknown context window size and costs, using sane defaults.” It means Aider does not know this model’s limits or prices, so it assumes defaults and shows no cost. For some model names it then also prints “Did you mean one of these?” with other providers’ copies of the model (for gpt-oss-20b it lists entries such as groq/openai/gpt-oss-20b). Ignore those: choosing one would send your request to that other provider. To hide the warning:

aider --model openai/gemma-4-26b --no-show-model-warnings

Aider also chooses its whole edit format for models it does not know. The model rewrites whole files instead of sending diffs, which is the simplest format for a model to follow but costs more output tokens on big files. You can try --edit-format diff with a stronger model.

How do I keep my API key out of my repo?

Put the two settings in a .env file in your project folder, which Aider reads (checked with Aider 0.86.2), and add .env to .gitignore so the key is never committed.

OPENAI_API_BASE=https://api.darkbloom.dev/v1
OPENAI_API_KEY=YOUR_DARKBLOOM_API_KEY

echo ".env" >> .gitignore

What do the common errors mean?

These are the messages you are most likely to see, with what causes each and the fix. All but the empty-balance row were reproduced with Aider 0.86.2. Aider retries after most API errors, waiting 0.2 seconds, then 0.5, 1, 2, 4, 8, 16 and 32 seconds, and then stops, so a refused request can look like a hang for about a minute.

Is Darkbloom private, and is it ready for production?

Not yet for sensitive work. Darkbloom’s quickstart calls the service “an experimental research prototype” and says not to use it in production applications, and its console labels it Public alpha. Darkbloom says prompts are encrypted to a verified provider Mac. Its security overview says the coordinator re-encrypts each request for the chosen provider and runs in a confidential VM. An independent review by Wavect (September 2026) reads Darkbloom’s technical documentation as saying that both the coordinator and the provider handle your prompt as plaintext inside protected boundaries.

Aider sends your chat and every file you add to it. Do not send secrets, customer data or code you are not allowed to share.

How this guide was checked

• A paid request from Aider to api.darkbloom.dev worked on October 22, 2026. Aider 0.86.2 on Linux, with OPENAI_API_BASE pointed at Darkbloom and --model openai/gemma-4-26b, edited a file in a git repo, applied the edit and committed it. Aider printed the warning and the whole edit format described above, and token counts but no cost. It made two requests, and Darkbloom’s usage log shows each billed at the $0.0001 minimum.
• The setup steps were compared with Aider’s own docs (linked under Sources) on October 22, 2026.
• Against a local test server that behaves like an OpenAI-compatible API, Aider 0.86.2 confirmed the request path (/v1/chat/completions), the Bearer header, that the openai/ prefix is removed before sending, that streaming is on by default, that no max_tokens is sent unless you set one, that a .env file is read, and the messages for a missing prefix, a missing key and a wrong key (the test server returned Darkbloom’s real “invalid API key” reply).
• The “not permitted to use model” row was reproduced against Darkbloom itself with a key that has an Allowed models list, including Aider’s retry waits. Darkbloom’s own text for an empty balance was not captured, because that needs an empty balance.
• The model list, context windows, features and prices come from GET /v1/models on October 22, 2026 (it needs a key). The key steps in the console come from the console’s own page text. We tested with a key that already existed, so we did not click through key creation ourselves.
• Our Darkbloom link was opened in a clean browser profile on October 22, 2026. It saved the referral code and the page said the code “is saved and will be applied after you sign in”. We did not create an account to test the sign-in step itself.

About this guide

BloomGauge is a free Mac app for people who run Darkbloom providers, so we benefit when Darkbloom has more paying demand. We are independent of Darkbloom and not endorsed by it. Our Darkbloom sign-in links carry our referral code, BLOOMGAUGE. If you sign in to Darkbloom after opening one, Darkbloom attaches the code to your account and pays us a share of your eligible token spend. Darkbloom funds that reward, so it does not change your price.

Sources

• Aider docs: OpenAI compatible APIs
• Aider docs: model warnings
• Aider docs: advanced model settings
• Aider polyglot leaderboard
• Darkbloom docs: quickstart
• Darkbloom docs: chat completions
• Darkbloom docs: authentication and API keys
• Darkbloom docs: add credits
• Darkbloom docs: usage history
• Darkbloom live prices (GET /v1/pricing)

Found something out of date? Tell us in #bloomgauge on the Darkbloom Slack or at Support.