Adding Environment Variables Guide

Comprehensive guidance for adding new environment variables to the Inkeep Agent Framework. This ensures consistency, documentation, and type safety across all packages.

CI Enforcement

Environment variable descriptions are enforced by CI. The check:env-descriptions script runs in CI and will fail if any variables in env.ts files are missing .describe() calls.

Run locally to check:

pnpm check:env-descriptions

Environment Architecture

The framework uses environment variables defined in multiple env.ts files:

Package	File	Purpose
agents-api	`agents-api/src/env.ts`	Main API server configuration
agents-core	`packages/agents-core/src/env.ts`	Shared core configuration
agents-cli	`agents-cli/src/env.ts`	CLI tool configuration

Note: The following files are auto-generated and should NOT be edited:

packages/agents-mcp/src/lib/env.ts (Generated by Speakeasy)

Required Steps for Adding Environment Variables

Step 1: Add to `.env.example`

Location: .env.example (root of repository)

Add the variable with a descriptive comment:

# ============ SECTION NAME ============
# Description of what this variable does
# Additional context if needed (e.g., where to get API keys)
MY_NEW_VARIABLE=default-value-or-empty

Example:

# ============ AI PROVIDERS ============
# Required for agent execution
# Get your API keys from:
# Anthropic: https://console.anthropic.com/
# OpenAI: https://platform.openai.com/
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

Step 2: Add to Relevant `env.ts` File(s)

Add the variable to the Zod schema with a .describe() call that matches the .env.example comment:

const envSchema = z.object({
  // ... existing variables ...

  MY_NEW_VARIABLE: z
    .string()
    .optional()
    .describe('Description of what this variable does'),
});

Step 3: Description Requirements

Every environment variable MUST have a .describe() call with a clear, concise description that:

Explains what the variable is used for
Matches the comment in .env.example
Includes helpful context (e.g., where to get API keys, default behavior)

Examples of good descriptions:

// AI Provider keys
ANTHROPIC_API_KEY: z
  .string()
  .describe('Anthropic API key for Claude models (required for agent execution). Get from https://console.anthropic.com/'),

// Database configuration
INKEEP_AGENTS_MANAGE_DATABASE_URL: z
  .string()
  .describe('PostgreSQL connection URL for the management database (Doltgres with Git version control)'),

// Authentication
BETTER_AUTH_SECRET: z
  .string()
  .optional()
  .describe('Secret key for Better Auth session encryption (change in production)'),

// Feature flags
LANGFUSE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable Langfuse LLM observability (set to "true" to enable)'),

Zod Schema Patterns

Required Variables

MY_REQUIRED_VAR: z
  .string()
  .describe('This variable is required for the application to function'),

Optional Variables

MY_OPTIONAL_VAR: z
  .string()
  .optional()
  .describe('Optional configuration for feature X'),

Variables with Defaults

MY_VAR_WITH_DEFAULT: z
  .string()
  .optional()
  .default('default-value')
  .describe('Configuration with a sensible default'),

Enum Variables

LOG_LEVEL: z
  .enum(['trace', 'debug', 'info', 'warn', 'error'])
  .default('info')
  .describe('Logging verbosity level'),

Numeric Variables

POOL_SIZE: z
  .coerce.number()
  .optional()
  .default(10)
  .describe('Maximum number of connections in the pool'),

Boolean Variables (as strings)

FEATURE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable feature X (set to "true" to enable)'),

Variables with Validation

JWT_SECRET: z
  .string()
  .min(32, 'JWT_SECRET must be at least 32 characters')
  .optional()
  .describe('Secret key for signing JWT tokens (minimum 32 characters)'),

ADMIN_EMAIL: z
  .string()
  .optional()
  .refine((val) => !val || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val), {
    message: 'Invalid email address',
  })
  .describe('Admin email address for notifications'),

Category Organization

Group related variables with comments in both .env.example and env.ts:

In `.env.example`:

# ============ DATABASE ============
INKEEP_AGENTS_MANAGE_DATABASE_URL=...
INKEEP_AGENTS_RUN_DATABASE_URL=...

# ============ AI PROVIDERS ============
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

In `env.ts`:

const envSchema = z.object({
  // Database
  INKEEP_AGENTS_MANAGE_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the management database'),
  INKEEP_AGENTS_RUN_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the runtime database'),

  // AI Providers
  ANTHROPIC_API_KEY: z
    .string()
    .describe('Anthropic API key for Claude models'),
  OPENAI_API_KEY: z
    .string()
    .optional()
    .describe('OpenAI API key for GPT models'),
});

Which `env.ts` File to Use?

Choose the appropriate file based on where the variable is used:

Use Case	File
API server configuration	`agents-api/src/env.ts`
Shared across packages	`packages/agents-core/src/env.ts`
CLI-specific	`agents-cli/src/env.ts`
Multiple packages	Add to `agents-core` and import where needed

Checklist for Adding Environment Variables

Before completing any environment variable addition, verify:

Common Mistakes to Avoid

Missing .describe() call - Every variable needs a description (CI will fail!)
Inconsistent descriptions - Keep .env.example and .describe() in sync
Wrong file - Add to the package that actually uses the variable
Missing validation - Add constraints for sensitive values (min length for secrets, email validation, etc.)
Editing auto-generated files - Never edit agents-mcp env files

adding-env-variables