Environment Variables

KB Labs reads a handful of environment variables at startup. Some control how the runtime finds its config files, some select a profile, some configure adapters, and a few are debug flags. This page lists them all, grouped by purpose. Entries marked with a file link are the ones I pulled directly from source; others are standard conventions that may or may not be enforced in every service.

The rule of thumb: env vars are for things that change per-deployment or per-environment. Plugin and product configuration belongs in kb.config.json, not in env. Secrets belong in env or a secret manager, not in kb.config.json.

Root resolution

These tell the runtime where to find .kb/kb.config.json and node_modules/@kb-labs/*. See core-workspace README for the full resolution algorithm.

Precedence: KB_PROJECT_ROOT > KB_LABS_WORKSPACE_ROOT > KB_LABS_REPO_ROOT > walk-up.

In dev mode (monorepo workspace) both roots coincide and you don't usually need any of these. In installed mode (installer drops the platform into a shared location and your project's .kb/ is elsewhere) the installer sets KB_PLATFORM_ROOT for you.

Profile selection

Read at useConfig() time in core-runtime/src/adapters/config-adapter.ts. Unknown profile IDs fall back to 'default'.

Logging and output

The CLI deliberately defaults to silent — no logs appear unless you set LOG_LEVEL, KB_LOG_LEVEL, or pass --debug. This is so pnpm kb <command> output is clean by default and users can opt into verbosity. See cli-bin/src/bin.ts.

Multi-tenancy

Used by the REST API rate-limit middleware and metrics collector (rest-api/src/middleware/rate-limit.ts). Requests carrying an explicit X-Tenant-ID header override the env var; requests without it fall back to this value.

Sandbox and plugin execution

Gateway

See gateway-app/src/bootstrap.ts and Gateway → Authentication.

Services

Each long-running service reads its own port env var plus NODE_ENV:

NODE_ENV is used consistently across services. 'production' disables Swagger UI, enables stricter CORS, and tightens a few other knobs; any other value (or unset) is treated as dev mode.

Marketplace client

From marketplace-cli/src/http.ts. KB_MARKETPLACE_URL takes precedence when present.

State broker

Adapter credentials

These are the env vars that first-party adapters read. Each adapter declares which vars it needs via its preset — llmAccessPreset grants the LLM ones, vectorStorePreset grants the vector-store ones, etc. See Plugins → Permissions for the full list.

LLM

Vector stores

Cache / storage

Most adapters take their primary config (connection URL, credentials) from platform.adapterOptions.<token> in kb.config.json. Env vars are for secrets that you don't want in the config file. The typical pattern is:

{
  "platform": {
    "adapterOptions": {
      "cache": {
        "url": "redis://localhost:6379"
      }
    }
  }
}

...with sensitive credentials kept in a secret manager or a .env file that isn't committed.

Observability and debug

All four KB_* flags read by core-sandbox/src/runner/initialization/observability-setup.ts.

Version reporting

Loading .env

runService() loads .env from the project root and, when it is distinct, the platform root before reading adapters or product config. Values already in the environment are not overwritten — an existing OPENAI_API_KEY in the parent shell wins over the one in .env.

The .env file is a dev-time convenience. In production, use a secret manager (Vault, AWS Secrets Manager, Kubernetes secrets) and set env vars on the service process directly.

Precedence

When multiple sources set the same variable, precedence is:

1. Explicit process.env from the parent shell (whatever's already set when the service starts).
2. .env file at the project root.
3. .env file at the platform root, when it is distinct from the project root.
4. Defaults hardcoded in the source.

CLI flags (--profile=<id>, --debug) override env vars for their respective settings.

Gotchas

• KB_LOG_LEVEL defaults to silent on the CLI only. Services default to 'info'. If you see no logs from the CLI, it's working as designed — set LOG_LEVEL=debug or pass --debug to see them.
• KB_TENANT_ID is a default, not an override. Incoming HTTP requests carrying X-Tenant-ID use the header value, not the env var. The env var is the fallback.
• Secrets in .env are still visible to the process. Adapter permissions (env.read in the plugin manifest) gate which env vars a plugin can read, but the service itself always has full access. Treat the service host as trusted.
• Legacy root vars work but are discouraged. KB_LABS_WORKSPACE_ROOT and KB_LABS_REPO_ROOT exist for backwards compatibility. New configs should use KB_PROJECT_ROOT.
• GATEWAY_JWT_SECRET has a dev fallback. Never rely on it in production — the gateway logs a prominent warning, but it doesn't refuse to start. Always set this explicitly in any non-dev deployment.

What to read next

• kb.config.json — the file env vars are meant to complement, not replace.
• Profiles — how KB_PROFILE is resolved.
• devservices.yaml — where kb-dev reads service env vars from.
• Gateway → Authentication — full story on GATEWAY_JWT_SECRET and GATEWAY_INTERNAL_SECRET.