Environment variables
Single-page reference for every environment variable @pleach/core reads — runtime flags, storage adapters, provider credentials, and observability.
The runtime reads a small, named set of environment variables. Anything not listed here is either an application-level concern or a sibling package's contract.
Runtime flags
Prop
Type
`@pleach/core` reads no `FEATURE_*` flags
A hard invariant (audit:no-process-env-feature-flags-in-core) keeps
@pleach/core free of process.env.FEATURE_* reads. Flags like
FEATURE_HARNESS_V2_RUNTIME and FEATURE_TOOL_CALL_RUNAWAY_HARD_BLOCK
are read by the embedding host (e.g. the Ivy application's
src/config/featureFlags.ts), never by the substrate — see
Host-read flags below. Setting them has no effect
on a bare @pleach/core install.
Provider credentials
These map to the native transport for the corresponding family. The
openrouter transport only needs OPENROUTER_API_KEY regardless of
which family is locked.
| Env var | Required for |
|---|---|
ANTHROPIC_API_KEY | native Anthropic transport. |
OPENAI_API_KEY | native OpenAI transport. |
GOOGLE_GENERATIVE_AI_API_KEY | native Google transport (pending). Primary; GOOGLE_API_KEY is accepted as a legacy fallback. |
DEEPSEEK_API_KEY | native DeepSeek transport (pending). |
MISTRAL_API_KEY | native Mistral transport (pending — Mistral has no native provider today; requests collapse to OpenRouter). |
OPENROUTER_API_KEY | The openrouter transport for any family. |
Storage credentials (when using @pleach/core/sessions Supabase adapter)
| Env var | Required for |
|---|---|
SUPABASE_URL | Both SupabaseAdapter (browser) and SupabaseSaver (server). |
SUPABASE_ANON_KEY | Browser-side SupabaseAdapter (RLS-bound). |
SUPABASE_SERVICE_ROLE_KEY | Server-side SupabaseSaver. |
The Memory and IndexedDB adapters don't read any env vars — they
exist for tests and for browser-only sessions where storage is owned
by the page.
Provider key resolution order
When a call fires, the runtime looks for credentials in this order and stops at the first hit:
- The
OrchestratorClientconstructor'sapiKeyoption (set by the embedding application). - The session's BYOK key, if the session was started with one.
- The matching process env var from the table above.
- If nothing matches, the call fails at session start rather than at the first request — a hard failure at construction time is easier to diagnose than a transient one at first traffic.
Host-read flags
These are read by an embedding host, not by @pleach/core. They are
listed here because they commonly appear alongside a Pleach
deployment, but a bare @pleach/core install ignores them entirely.
| Env var | Read by | Effect |
|---|---|---|
FEATURE_HARNESS_V2_RUNTIME | Host (e.g. Ivy featureFlags.ts) | Host-level toggle for whether the app routes turns through the runtime substrate at all; when false, the host's routes return 503. No effect inside @pleach/core. |
FEATURE_TOOL_CALL_RUNAWAY_HARD_BLOCK | Host (e.g. Ivy featureFlags.ts) | Host-side gate for the tool-call runaway hard-block enforcement. Default-on (only "false" disables). No effect inside @pleach/core. |
Retired flags
| Env var | Status |
|---|---|
HARNESS_C1_DUAL_WRITE | Retired. Pre-1.0 dual-write flag; the runtime now writes the canonical event log shape unconditionally. Setting it has no effect. |