Environment Configuration

Overview

The Inkeep Agents framework uses a centralized environment configuration. This approach provides a single source of truth for all environment variables across the monorepo, eliminating duplication and simplifying configuration management.

Configuration Structure

Single Root Configuration

All packages in the monorepo reference a single .env file at the repository root. This is different from the typical approach of having separate .env files per package.

agents-4/
├── .env                    # Main configuration (gitignored)
├── .env.example            # Template with all variables
└── packages/
    └── agents-core/
        └── src/env.ts      # Centralized env loader

Loading Priority

Environment variables are loaded in the following order (highest priority first):

1. /package-name/.env Package specific configuration
2. .env - Main configuration file
3. ~/.inkeep/config - User-global settings (shared across all repo copies)
4. .env.example - Default values

This hierarchy allows for flexible configuration management across different scenarios. If you have .env or .env.local in a package directory, they will override the root .env or .env.local for that package.

Use Cases

1. Basic Local Development

For local development, pnpm setup-dev creates your .env and initializes databases. You only need to add your AI provider API keys:

# Run setup (creates .env, starts databases, runs migrations)
pnpm setup-dev

# Add your API keys to .env
vim .env

# Start development
pnpm dev

Troubleshooting

Auto-login not working

The Manage UI auto-logs you in during local development. If you're redirected to the login page instead, your .env is likely missing the auth variables. Ensure these are set:

INKEEP_AGENTS_MANAGE_UI_USERNAME=admin@example.com
INKEEP_AGENTS_MANAGE_UI_PASSWORD=adminADMIN!@12
BETTER_AUTH_SECRET=your-secret-key-change-in-production

Then run pnpm db:auth:init to create the admin user, and restart pnpm dev. Check the browser console for [DevAutoLogin] messages if the issue persists.

Environment variables not loading

1. Check loading order - later sources override earlier ones
2. Verify file paths are correct
3. Ensure packages/agents-core is built: pnpm --filter @inkeep/agents-core build

Missing variables in production

Ensure all required variables are set in your deployment environment. The application will fail fast if critical variables are missing.

Database connection issues

• For SQLite: Make sure you are using an absolute path to the db file