Configuration Management

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)

import { defineConfig } from '@inkeep/agents-cli/config';
import 'dotenv/config';

export default defineConfig({
  // Required: Your tenant identifier
  tenantId: 'my-company',

  // Management API configuration
  agentsManageApi: {
    url: 'http://localhost:3002',
    apiKey: process.env.MANAGE_API_KEY, // Optional: API key for authentication
  },

  // Runtime API configuration
  agentsRunApi: {
    url: 'http://localhost:3003',
    apiKey: process.env.RUN_API_KEY, // Optional: API key for authentication
  },

  // Optional: Output directory for generated files
  outputDirectory: './output',
});

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. :::

import { defineConfig } from '@inkeep/agents-cli/config';

export default defineConfig({
  // Required: Your tenant identifier
  tenantId: 'my-company',

  // API endpoints (legacy format - DEPRECATED)
  agentsManageApiUrl: 'http://localhost:3002', // ⚠️ Use agentsManageApi.url instead
  agentsRunApiUrl: 'http://localhost:3003',     // ⚠️ Use agentsRunApi.url instead
});

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:

my-agent-workspace/
├── inkeep.config.ts          # Workspace configuration (shared)
├── .env                       # Environment variables
├── package.json
├── agents/                    # Your agent definitions
│   ├── qa-agent.graph.ts
│   ├── support-agent.graph.ts
│   └── router.graph.ts
└── tools/                     # Custom tools (optional)
    └── search-tool.ts

Key points:

Single config per workspace: One inkeep.config.ts at 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 --config flag

Config File Discovery

The CLI uses a sophisticated discovery mechanism to locate your configuration:

Search Pattern

Explicit Path: If --config flag is provided, use that file directly
Upward Search: Starting from current working directory:
- Look for inkeep.config.ts in 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
Error Handling: If no config found, provide helpful error message

Example Discovery

# Directory structure (workspace root)
/home/user/workspace/
├── package.json              # Workspace package.json
├── tsconfig.json             # Workspace TypeScript config
├── inkeep.config.ts          # ✅ Config file at workspace root
├── my-agents/                # Project directory
│   ├── index.ts              # Project entry point
│   └── subfolder/
│       └── current-location/ # CLI run from here
└── other-project/

# CLI searches: current-location → subfolder → my-agents → workspace → FOUND!

Configuration Priority

Settings are resolved in this order (highest to lowest priority):

1. CLI Flags (Highest Priority)

Command-line flags override all other settings:

# Override API URL
inkeep push --agents-manage-api-url https://api.production.com

# Override config file location
inkeep pull --config /path/to/custom.config.ts

# Override environment
inkeep push --env production

2. Environment Variables

Environment variables override config file values:

# Set via environment
export INKEEP_AGENTS_MANAGE_API_URL=https://api.staging.com
export INKEEP_TENANT_ID=staging-tenant
export INKEEP_ENV=staging

# Now CLI commands use these values
inkeep push

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:

export default defineConfig({
  tenantId: 'my-tenant',
  agentsManageApiUrl: 'http://localhost:3002',
  // These values used unless overridden
});

4. Built-in Defaults (Lowest Priority)

Default values used when not specified elsewhere:

const defaults = {
  agentsManageApiUrl: 'http://localhost:3002',
  agentsRunApiUrl: 'http://localhost:3003',
  apiTimeout: 30000,
  retryAttempts: 3,
};

Advanced Configuration

TypeScript Support

The config system is fully typed, providing IntelliSense and validation:

import { defineConfig, ConfigOptions } from '@inkeep/agents-cli/config';

// Get full type safety
const config: ConfigOptions = {
  tenantId: 'my-tenant', // ✓ Required
  invalidOption: true,   // ✗ TypeScript error
};

export default defineConfig(config);

Dynamic Configuration

You can use environment-based logic in your workspace config:

// inkeep.config.ts at workspace root
import { defineConfig } from '@inkeep/agents-cli/config';

const isDevelopment = process.env.NODE_ENV === 'development';

export default defineConfig({
  tenantId: process.env.TENANT_ID || 'default-tenant',
  agentsManageApiUrl: isDevelopment
    ? 'http://localhost:3002'
    : 'https://api.production.com',
  apiTimeout: isDevelopment ? 60000 : 30000,
});

Note: This single config file manages all projects within the workspace.

Multiple Configurations

For workspaces requiring different configurations:

// inkeep.config.ts (main config at workspace root)
export default defineConfig({
  tenantId: 'production-tenant',
  agentsManageApiUrl: 'https://api.production.com',
});

// inkeep.dev.config.ts (development config at workspace root)
export default defineConfig({
  tenantId: 'dev-tenant',
  agentsManageApiUrl: 'http://localhost:3002',
});

# Use development config (specify from any project directory)
inkeep push --config ../inkeep.dev.config.ts
# or with absolute path
inkeep push --config /path/to/workspace/inkeep.dev.config.ts

Configuration Validation

The CLI validates configuration at runtime:

Required Fields

export default defineConfig({
  // ✗ Error: tenantId is required
});

URL Validation

export default defineConfig({
  tenantId: 'my-tenant',
  agentsManageApiUrl: 'invalid-url', // ✗ Error: Invalid URL format
});

Type Validation

export default defineConfig({
  tenantId: 'my-tenant',
  apiTimeout: 'thirty seconds', // ✗ Error: Expected number
});

Debugging Configuration

View Current Configuration

# View all configuration values
inkeep config get

# View specific value
inkeep config get tenantId

# View with specific config file
inkeep config get --config ./custom.config.ts

Configuration Sources

The CLI shows where each setting comes from:

inkeep config get tenantId
# Output: my-tenant (from environment variable)

inkeep config get agentsManageApiUrl
# Output: http://localhost:3002 (from config file)

Best Practices

1. Environment-Specific Configs

Use different configs for different environments:

# Development
inkeep.config.ts          # Local development settings

# Staging
inkeep.staging.config.ts  # Staging environment settings

# Production
inkeep.prod.config.ts     # Production environment settings

2. Secret Management

Never commit secrets to config files:

// ✗ Bad: Hardcoded secrets
export default defineConfig({
  tenantId: 'my-tenant',
  apiKey: 'sk-secret-key', // Don't do this!
});

// ✓ Good: Use environment variables
export default defineConfig({
  tenantId: 'my-tenant',
  // API keys handled via environment-specific credential configs
});

3. Documentation

Document your configuration options:

export default defineConfig({
  // Production tenant for main application
  tenantId: 'acme-corp-prod',

  // Use staging API for development
  agentsManageApi: {
    url: process.env.NODE_ENV === 'development'
      ? 'https://api-staging.acme.com'
      : 'https://api.acme.com',
    apiKey: process.env.MANAGE_API_KEY,
  },

  agentsRunApi: {
    url: process.env.NODE_ENV === 'development'
      ? 'https://run-staging.acme.com'
      : 'https://run.acme.com',
    apiKey: process.env.RUN_API_KEY,
  },
});

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):

import { defineConfig } from '@inkeep/agents-cli/config';

export default defineConfig({
  tenantId: 'my-tenant',
  agentsManageApiUrl: 'http://localhost:3002',
  agentsRunApiUrl: 'http://localhost:3003',
});

After (Nested Format):

import { defineConfig } from '@inkeep/agents-cli/config';
import 'dotenv/config';

export default defineConfig({
  tenantId: 'my-tenant',
  agentsManageApi: {
    url: 'http://localhost:3002',
    // Optional: Add API key for authentication
    apiKey: process.env.MANAGE_API_KEY,
  },
  agentsRunApi: {
    url: 'http://localhost:3003',
    // Optional: Add API key for authentication
    apiKey: process.env.RUN_API_KEY,
  },
});

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_SECRET environment 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

Error: Could not find inkeep.config.ts

Solutions:

Ensure inkeep.config.ts exists at workspace root (same level as package.json)
CLI searches upward - make sure you're running from within the workspace
Use --config flag 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

Error: Invalid configuration: tenantId is required

Solutions:

Add required tenantId field
Check for typos in field names
Verify TypeScript compilation

Environment Issues

Warning: INKEEP_TENANT_ID environment variable overrides config

Solutions:

Unset environment variable: unset INKEEP_TENANT_ID
Use --config to override with specific file
Check .env files 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.

Configuration Management

On this page