# Environment variables (/docs/env-vars)



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 [#runtime-flags]

<TypeTable
  type="{
  HARNESS_MOCK_MODE: {
    type: 'boolean',
    default: 'false',
    description: 'Run the runtime against in-memory storage and a deterministic mock provider. No real credentials needed; useful for smoke tests and CI. This is the only feature-flag env var `@pleach/core` itself reads.',
  },
}"
/>

<Callout type="info" title="`@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](#host-read-flags) below. Setting them has no effect
  on a bare `@pleach/core` install.
</Callout>

## Provider credentials [#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) [#storage-credentials-when-using-pleachcoresessions-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 [#provider-key-resolution-order]

When a call fires, the runtime looks for credentials in this order and
stops at the first hit:

1. The `OrchestratorClient` constructor's `apiKey` option (set by the
   embedding application).
2. The session's BYOK key, if the session was started with one.
3. The matching process env var from the table above.
4. 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 [#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 [#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. |

## Where to go next [#where-to-go-next]

<Cards>
  <Card title="CLI" href="/docs/cli" description="The pleach binary — what it does today and how to apply migrations." />

  <Card title="Deployment" href="/docs/deployment" description="Production checklist, including which env vars must be set per environment." />

  <Card title="Providers" href="/docs/providers" description="Family lock, transports, and where each provider credential lands." />

  <Card title="Multi-tenant" href="/docs/multi-tenant" description="BYOK keys per tenant and the gateway-plugin alternative." />
</Cards>