Credentials

Real models need API keys and endpoints. You don’t configure them up front: the first run that needs a credential asks for it, and offers to save it. Keys stay off your command lines, out of your params, and out of the condition hash.

The first run asks

A model id’s prefix (anthropic/… → anthropic) names a credential set. The first interactive run that needs a set you don’t have asks at the gate, before anything launches:

adb: this run needs credential set 'anthropic' — setting it up now
ANTHROPIC_API_KEY [unset]: ****
ANTHROPIC_BASE_URL [default: https://api.anthropic.com]:
save 'anthropic' for future runs? [Y/n]:
name this profile [default]:
adb: [258b80e5323e r1] run 01KYS…H3 started
adb:   ▸ watch  http://127.0.0.1:8340/#/runs/01KYS…H3
adb:   ▸ store  ~/.local/share/adb/runs/258b80e5323e…/01KYS…H3

The gate is the last thing before the run moves, so the link to watch it live is the last thing printed — click it (if the viewer isn’t up yet, the line above it says so, and how to start it).

• Secret prompts are hidden — never echoed, and never on the command line. (There is deliberately no KEY=VALUE argv form: argv shows up in ps and shell history.)
• Enter accepts a shown [default: …].
• save? [Y/n] — Y stores the set for every future run; n uses it for this run only and forgets it.
• The profile name is for keeping several credentials for the same provider — Enter is the right answer until you need that (see Profiles).
• Headless runs never hang on a prompt: with piped stdin or --json, a missing set refuses the run and prints the credentials set command to run instead.

A name is a condition, a key is environment

model NAME  →  the condition   (a model param, e.g. openai/qwen3.5-9b)
endpoint    →  environment     (not a condition)
API key     →  environment     (not a condition)

Two researchers each running their own local qwen3.5-9b server should land in the same condition bucket — the science is “what does qwen3.5-9b do”, not “what does it do at my URL with my key”. So endpoints and keys are never experiment params, and changing them never changes a condition. See Experiments, conditions, runs.

Setting and managing them yourself

The same prompts, standalone — for setting up in advance or rotating a key:

nix run .#adb-runner -- \
  credentials set anthropic

nix run .#adb-runner -- \
  credentials list

Also credentials remove <name> and credentials path. credentials set re-prompts with your current values as defaults, so changing one field is Enter-past-the-rest; to script it, pipe one line per prompt on stdin — values still never touch argv. What the dialogue asks, per built-in name:

Profiles

A credential set can hold several profiles — a work key and a personal key for the same provider, a proxy endpoint next to the direct one. The default profile is what every run uses silently; the moment a set has named profiles, interactive runs ask:

which 'openai' credentials? [default] work personal new:
always use 'work' for 'concordia'? [y/N]:

• Enter takes the bracketed default; typing a name takes that profile; new creates one on the spot (same prompts as setup, then a name).
• always use …? [y/N] — y remembers the choice per experiment, so this experiment never asks again. Remembered choices live in ~/.config/adb/preferences.toml — profile names only, never values, so it isn’t secret; edit or delete lines freely to forget.
• Create and edit profiles directly with credentials set openai.work; delete one with credentials remove openai.work.
• Headless runs never see the picker: a remembered choice wins, else the default profile, else the run is refused with the fix.
• Profiles are atomic — a profile missing a field never borrows it from another profile.
• The profile choice is environment, never identity: runs of the same model under different profiles land in the same condition bucket.

The store

~/.config/adb/credentials.toml      # mode 0600, one [<set>.<profile>] section each
~/.config/adb/preferences.toml      # remembered per-experiment choices (names only)

The path honors $XDG_CONFIG_HOME; $ADB_CREDENTIALS_FILE overrides it entirely. That variable is also the CI story: your pipeline materializes this file from its own secret manager and points the variable at it — chmod 600 it as you do, because a store readable by group or others is refused outright (with the chmod to run), the same way ssh treats a leaky private key. Base URLs are validated as you type them (an http(s):// scheme is required), so a typo is one retype instead of a cryptic client error mid-run.

The file is yours to edit by hand — credentials set is a convenience, not a gatekeeper. A set is a free-form field map: any env var you add to a section is injected into every run that routes to it, including vars the dialogue never asks about (an org id, an API version, extra vendor knobs). The dialogue only knows the common shape; the store carries whatever you put in it.

How credentials reach the experiment

A run’s environment is constructed, not inherited — there is no passthrough of your shell into an experiment. A run receives exactly: a minimal set of system basics (PATH, HOME, locale), the credential sets this run routes to, and the ADB_* run vars. A stray key exported in your shell cannot leak into a run, because nothing ambient ever enters one.

Because the environment is constructed, it is also recorded: each run’s record lists the env var names it received and which set each came from — secret values ablated, non-secret values (like base URLs) kept as covariates. What a run ran with is never a mystery; what the secrets were is never written down.

The trust caveat

Running third-party code with your keys is a real trust decision: an experiment process receives the credentials routed to it and could misuse them. Today’s mitigations: experiments in the monorepo are reviewed (nixpkgs-style), a run receives only the sets it routes to — never your whole keyring — and nothing ambient is exposed. VM-isolated execution with a recording proxy, where the raw key never enters the experiment process at all, is the planned next step (see docs/plan/credentials.md in the repo for the design).