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:

• Variable added to .env.example with descriptive comment

• Variable added to relevant env.ts file(s)

• .describe() call added with clear description

• Description matches .env.example comment

• Appropriate Zod type used (string, number, enum, etc.)

• optional() added if variable is not required

• default() added if there's a sensible default

• Validation added if needed (min, max, refine, etc.)

• Variable grouped with related variables (using comments)

• pnpm check:env-descriptions passes locally

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