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