Aider Custom Endpoints: Keys, Roles and Verification

Aider's provider flags are a quiet superpower most users never touch: any model behind any key, switched per session, with git-native safety throughout. The default key works until the bill arrives; custom endpoints work identically for less, or with models the default never offered. This guide covers endpoint configuration precisely, the migrate-billing-before-models sequence that prevents misattribution, verification routines, and team conventions that keep every ticket on the right model.

Endpoint configuration, precisely

Point Aider with the provider prefix on --model, the matching key in the environment, and the base URL configured for gateway endpoints. Copy model strings from provider catalogs exactly — Aider passes them through verbatim, so retired aliases and renames fail at the provider with messages that blame everything except the string. Verify with one trivial ticket; identical diffs and commits confirm plumbing completely.

Resist compound changes: new key with familiar model first, then model experiments on proven billing. Each round gets its own verification ticket. This discipline feels slow for exactly one afternoon; then every future key or model change takes minutes with total confidence. Document the working combination per provider so setups copy instead of being rediscovered.

• Provider prefix plus environment key
• Base URL for gateway endpoints
• Exact strings from catalogs
• Trivial-ticket verification

Billing before models, always

When moving keys, keep the trusted model so the only variable is billing. When moving models, keep the proven key so the only variable is capability. Violating this sequence creates compound mysteries where neither suspect can be cleared — the most expensive debugging shape in configuration work. Downgrade tiers only on routine tickets, keeping flagships assigned to architecture and subtle bugs.

Verify with diffs as the oracle: identical inputs should produce behaviorally identical outputs across billing changes. Any behavioral difference indicts the configuration, not the model — investigate before adapting workflows around breakage. The sequence is unglamorous and nearly infallible. Boring migrations succeed; exciting ones become post-mortems.

• Same model, new billing first
• Diffs as the test oracle
• Tier down on routine only
• Patience as professionalism

Roles across any endpoint

Custom endpoints support Aider's full role system: architect flag for planning with strong reasoning, editor flag for execution with cheap speed. The savings multiply per file touched, which is exactly where Aider operates — bulk refactors across dozens of files turn per-token gaps into per-ticket windfalls. Switching takes a flag; the habit takes a week; the payoff is permanent.

Default cheap and escalate deliberately on every endpoint equally. The role pattern is provider-agnostic because it exploits task shape, not vendor quirks. Teams that adopt roles universally spend dramatically less than single-model teams on identical tickets. Write the role convention down; unwritten routing decays to flagship-default within weeks under deadline pressure.

• Architect plans, editor executes
• Strong for judgment, cheap for bulk
• Per-session flags, zero friction
• Savings multiply per file touched

Fallback keys as insurance

Keep at least two keys configured permanently and switch via environment variables — never reinstalls, never reconfigures, just a different export. Test the fallback monthly with a trivial task; untested redundancy fails exactly when the primary does, which is when you needed it most. Document each key's purpose: daily driver, cheap bulk, strong escalation.

Outages, deprecations and quota surprises strike every provider eventually; the team with a warm fallback continues in minutes while others wait hours. The insurance costs nothing idle and pays on first use. Make fallback testing a calendar event rather than an intention — intentions expire, calendar events execute. This is operations basics applied to AI keys.

• Both keys configured permanently
• Environment switching, not reinstalls
• Monthly fallback tests
• Documented key purposes

Team routing that lasts

Write model-to-task mapping with reasons: default, escalation and bulk choices per ticket shape. Store alongside working provider configurations in team docs. Review quarterly as generations turn over; today's careful mapping decays without maintenance like every living document. New teammates copy working configs on day one instead of improvising for months.

Maintain telemetry per key: tokens, costs, acceptance signals. Let data retire escalation triggers where steady success proves lower tiers sufficient. The mapping pays rent every ticket; an hour of quarterly maintenance protects it indefinitely. Teams with written routing spend less with less thought than teams improvising per ticket — compounding returns on a one-page document.

• Model-to-task mapping written
• Quarterly generation reviews
• Telemetry per key maintained
• Living routing document

Frequently asked questions

How do I point Aider at a custom endpoint?

Set the provider prefix with --model, export the matching key, configure the base URL for gateways. Verify with a trivial ticket; identical diffs confirm plumbing before real work depends on it.

Migrate key or model first?

Keep your trusted model on the new key first so only billing changes. Verify diffs and commits, then tier downward on routine tickets while keeping flagships for hard problems.

How do I confirm model names?

List models via provider dashboard or API and paste exact strings. Retired aliases fail confusingly; a two-minute catalog check beats a two-hour config mystery.

Can different roles use different models?

Yes. Architect and editor roles take separate --model flags: strong reasoning for planning, cheap speed for bulk execution. Per-session switching makes the habit frictionless.

How do I maintain a fallback key?

Keep both keys configured and switch via environment; test the fallback monthly with a trivial task. Untested redundancy fails exactly when primary does.

Related guides

• Aider Running Costs: Keys, Models and Habits That Cut Bills
• Aider Model Setup: Architect Splits, Providers and Team Defaults

Last updated: 2026-09-28