Configuration Management
Copy page
Configure your Inkeep Agent workspace with inkeep.config.ts - workspace-level settings for all agents and CLI commands
Overview
Inkeep Agent projects use a hierarchical configuration system that combines file-based configuration, environment variables, and command-line overrides. This flexible approach supports different deployment environments while maintaining developer-friendly defaults.
Configuration File Format
inkeep.config.ts
The workspace-level configuration file for your Inkeep project. This file defines settings that apply to your entire workspace, including:
- Tenant and project identification for organizing your agents
- API endpoints for the Management and Runtime APIs
- Authentication credentials for secure API access
- Output directories for generated files
:::tip
inkeep.config.ts is typically placed at the root of your workspace (not within individual packages or subdirectories). All CLI commands in the workspace will discover and use this configuration automatically.
:::
The configuration file supports both nested (recommended) and flat configuration formats:
Nested Format (Recommended)
Flat Format (Deprecated - Legacy Only)
:::warning Deprecated: The flat configuration format is maintained for backward compatibility only. New projects should use the nested format above. :::
Configuration Options
Nested Format Options
| Option | Type | Description | Default |
|---|---|---|---|
tenantId | string | Required. Unique identifier for your tenant | - |
agentsManageApi | object | Management API configuration | - |
agentsManageApi.url | string | Management API endpoint URL | 'http://localhost:3002' |
agentsManageApi.apiKey | string | Optional API key for Management API authentication | - |
agentsRunApi | object | Runtime API configuration | - |
agentsRunApi.url | string | Runtime API endpoint URL | 'http://localhost:3003' |
agentsRunApi.apiKey | string | Optional API key for Runtime API authentication | - |
outputDirectory | string | Output directory for generated files | - |
manageUiUrl | string | Optional Management UI URL | 'http://localhost:3000' |
Flat Format Options (Deprecated - Legacy)
| Option | Type | Description | Default |
|---|---|---|---|
tenantId | string | Required. Unique identifier for your tenant | - |
agentsManageApiUrl | string | ⚠️ Deprecated. Management API endpoint. Use agentsManageApi.url instead | 'http://localhost:3002' |
agentsRunApiUrl | string | ⚠️ Deprecated. Runtime API endpoint. Use agentsRunApi.url instead | 'http://localhost:3003' |
outputDirectory | string | Output directory for generated files | - |
manageUiUrl | string | Optional Management UI URL | 'http://localhost:3000' |
Note: API keys should be provided via the config file (using environment variables) rather than using legacy INKEEP_AGENTS_*_BYPASS_SECRET environment variables.
Workspace Structure
The inkeep.config.ts file is a workspace-level configuration that applies to all agent definitions and CLI commands within your project. Here's a typical workspace structure:
Key points:
- Single config per workspace: One
inkeep.config.tsat the workspace root - Shared settings: All agent files use the same tenant, API endpoints, and credentials
- CLI discovery: Commands run from any subdirectory will find the root config
- Monorepo support: In monorepos, place config at the root or use
--configflag
Config File Discovery
The CLI uses a sophisticated discovery mechanism to locate your configuration:
Search Pattern
- Explicit Path: If
--configflag is provided, use that file directly - Upward Search: Starting from current working directory:
- Look for
inkeep.config.tsin current directory - If not found, move to parent directory
- Repeat until found or reach filesystem root
- Config file should be at the same level as
package.json/tsconfig.json
- Look for
- Error Handling: If no config found, provide helpful error message
Example Discovery
Configuration Priority
Settings are resolved in this order (highest to lowest priority):
1. CLI Flags (Highest Priority)
Command-line flags override all other settings:
2. Environment Variables
Environment variables override config file values:
Supported Environment Variables:
| Variable | Config Equivalent | Description |
|---|---|---|
INKEEP_TENANT_ID | tenantId | Tenant identifier |
INKEEP_AGENTS_MANAGE_API_URL | agentsManageApiUrl | Management API URL |
INKEEP_AGENTS_RUN_API_URL | agentsRunApiUrl | Runtime API URL |
INKEEP_ENV | - | Environment name for credential loading |
3. Config File Values
Values explicitly set in your inkeep.config.ts:
4. Built-in Defaults (Lowest Priority)
Default values used when not specified elsewhere:
Advanced Configuration
TypeScript Support
The config system is fully typed, providing IntelliSense and validation:
Dynamic Configuration
You can use environment-based logic in your workspace config:
Note: This single config file manages all projects within the workspace.
Multiple Configurations
For workspaces requiring different configurations:
Configuration Validation
The CLI validates configuration at runtime:
Required Fields
URL Validation
Type Validation
Debugging Configuration
View Current Configuration
Configuration Sources
The CLI shows where each setting comes from:
Best Practices
1. Environment-Specific Configs
Use different configs for different environments:
2. Secret Management
Never commit secrets to config files:
3. Documentation
Document your configuration options:
Migration Guide
Migrating from Flat to Nested Format
If you're using the legacy flat format, here's how to migrate to the new nested format:
Before (Flat Format):
After (Nested Format):
Benefits of the Nested Format:
- Explicit API Key Management: Store API keys directly in config (via environment variables) with clear, organized structure
- Better Organization: Related configuration grouped together
- Type Safety: Improved IntelliSense and type checking
- Future-Proof: New API configuration options can be added without cluttering the top-level config
- Cleaner Environment: No need for legacy
INKEEP_AGENTS_*_BYPASS_SECRETenvironment variables
Backward Compatibility: The CLI fully supports both formats. You can continue using the flat format without any changes, or migrate at your convenience.
Troubleshooting
Config Not Found
Solutions:
- Ensure
inkeep.config.tsexists at workspace root (same level aspackage.json) - CLI searches upward - make sure you're running from within the workspace
- Use
--configflag to specify absolute or relative path to config file - Check file name (must be exactly
inkeep.config.ts) - Verify you're not running from a completely separate directory tree
Invalid Configuration
Solutions:
- Add required
tenantIdfield - Check for typos in field names
- Verify TypeScript compilation
Environment Issues
Solutions:
- Unset environment variable:
unset INKEEP_TENANT_ID - Use
--configto override with specific file - Check
.envfiles for conflicting values
The configuration system provides the flexibility to adapt your Inkeep Agent projects to different environments while maintaining consistency and type safety across your development workflow.