Configuration

Every setting can come from the environment or from code. Code wins, so a test can pin its Phase while the environment configures everything else.

The settings

Setting	Environment	Values	Default
Phase	`SHIMMY_PHASE`	`dev`, `tuning`, `production`	`dev`
Dev source	`SHIMMY_DEV_SOURCE`	`local`, `remote`	`local` under a test runner, else `remote`
Recording mode	`SHIMMY_RECORDING`	`auto`, `record`, `strict`	`strict` under a test runner in CI, else `auto`
Production mode	`SHIMMY_PRODUCTION`	`managed`, `passthrough`	`managed`
Recordings directory	`SHIMMY_RECORDINGS_DIR`	a path	`shimmy/recordings`
Lockfile	`SHIMMY_LOCKFILE`	a path	`shimmy.lock`
API key	`SHIMMY_API_KEY`	`sk-opt-…`	required
Base URL	`SHIMMY_BASE_URL`	a URL	`https://rfa-labs.com`

An unknown value fails when the client is constructed, not on the first call.

const shimmy = new Shimmy({
  phase: 'dev',             // 'dev' | 'tuning' | 'production'
  devSource: 'local',       // Dev: replay from the repo, or 'remote' from Shimmy
  recording: 'auto',        // Dev: 'auto' | 'record' | 'strict'
  production: 'managed',    // Production: 'managed' | 'passthrough'
  recordingsDir: 'shimmy/recordings',
  lockfile: 'shimmy.lock',
});

OPTIMIZER_API_KEY and OPTIMIZER_BASE_URL are still read when the SHIMMY_ names are unset.

Test runners

“Under a test runner” means:

SDK	Detected by
Python	pytest (the bundled plugin)
TypeScript	`VITEST`, `JEST_WORKER_ID` or `NODE_TEST_CONTEXT` in the environment
Rust	the crate’s `testing` feature, enabled on your dev-dependency
any	`SHIMMY_TEST=1`

“In CI” means CI is set to anything but 0, false or no — which every mainstream CI service does.

Passthrough (Rust)

The TypeScript and Python SDKs pass through with the client you wrapped. Rust’s chat() needs to know where your provider is:

Option	Environment	Default
`provider_base_url`	`SHIMMY_PROVIDER_BASE_URL`, then `OPENAI_BASE_URL`	`https://api.openai.com/v1`
`provider_api_key`	`SHIMMY_PROVIDER_API_KEY`, then `OPENAI_API_KEY`	required in passthrough

Account settings

Mode, Allowed providers, provider keys, alerts, content capture and guardrails belong to the account, not the process. Set them in the dashboard (Settings), on the control plane, or as config as code.