Multi-Level Configuration

kdn supports configuration at multiple levels, allowing you to customize workspace settings for different contexts. Configurations are automatically merged with proper precedence, making it easy to share common settings while still allowing project and agent-specific customization.

Configuration Levels¶

1. Workspace Configuration (.kaiden/workspace.json) - Stored in your project repository - Shared with all developers - Used by all agents - Committed to version control

2. Global Project Configuration (~/.kdn/config/projects.json with "" key) - User-specific settings applied to all projects - Stored on your local machine (not committed to git) - Perfect for common settings like .gitconfig, SSH keys, or global environment variables - Never shared with other developers

3. Project-Specific Configuration (~/.kdn/config/projects.json) - User-specific settings for a specific project - Stored on your local machine (not committed to git) - Overrides global settings for this project - Identified by project ID (git repository URL or directory path)

4. Agent-Specific Configuration (~/.kdn/config/agents.json) - User-specific settings for a specific agent (Claude, Goose, etc.) - Stored on your local machine (not committed to git) - Overrides all other configurations - Perfect for agent-specific environment variables or tools

Configuration Precedence¶

When registering a workspace, configurations are merged in this order (later configs override earlier ones):

1. Workspace (.kaiden/workspace.json) - Base configuration from repository
2. Global (projects.json "" key) - Your global settings for all projects
3. Project (projects.json specific project) - Your settings for this project
4. Agent (agents.json specific agent) - Your settings for this agent

Example: If DEBUG is defined in workspace config as false, in project config as true, and in agent config as verbose, the final value will be verbose (from agent config).

Storage Location¶

User-specific configurations are stored in the kdn storage directory:

• Default location: ~/.kdn/config/
• Custom location: Set via --storage flag or KDN_STORAGE environment variable

The storage directory contains: - config/agents.json - Agent-specific environment variables and mounts - config/projects.json - Project-specific and global environment variables and mounts - config/<agent>/ - Agent default settings files (e.g., config/claude/.claude.json)

Agent Configuration File¶

Location: ~/.kdn/config/agents.json

Format:

{
  "claude": {
    "environment": [
      {
        "name": "DEBUG",
        "value": "true"
      }
    ],
    "mounts": [
      {"host": "$HOME/.claude-config", "target": "$HOME/.claude-config"}
    ]
  },
  "goose": {
    "environment": [
      {
        "name": "GOOSE_MODE",
        "value": "verbose"
      }
    ]
  }
}

Each key is an agent name (e.g., claude, goose). The value uses the same structure as workspace.json.

Project Configuration File¶

Location: ~/.kdn/config/projects.json

Format:

{
  "": {
    "mounts": [
      {"host": "$HOME/.gitconfig", "target": "$HOME/.gitconfig"},
      {"host": "$HOME/.ssh", "target": "$HOME/.ssh"}
    ]
  },
  "https://github.com/openkaiden/kdn/": {
    "environment": [
      {
        "name": "PROJECT_VAR",
        "value": "project-value"
      }
    ],
    "mounts": [
      {"host": "$SOURCES/../kaiden-common", "target": "$SOURCES/../kaiden-common"}
    ]
  },
  "/home/user/my/project": {
    "environment": [
      {
        "name": "LOCAL_DEV",
        "value": "true"
      }
    ]
  }
}

Special Keys: - Empty string "" - Global configuration applied to all projects - Git repository URL - Configuration for all workspaces in that repository (e.g., github.com/user/repo) - Directory path - Configuration for a specific directory (takes precedence over repository URL)

Use Cases¶

Global Settings for All Projects:

{
  "": {
    "mounts": [
      {"host": "$HOME/.gitconfig", "target": "$HOME/.gitconfig"},
      {"host": "$HOME/.ssh", "target": "$HOME/.ssh"},
      {"host": "$HOME/.gnupg", "target": "$HOME/.gnupg"}
    ]
  }
}

Project-Specific API Keys:

{
  "github.com/company/project": {
    "environment": [
      {
        "name": "API_KEY",
        "secret": "project-api-key"
      }
    ]
  }
}

Agent-Specific Debug Mode:

{
  "claude": {
    "environment": [
      {
        "name": "DEBUG",
        "value": "true"
      }
    ]
  }
}

Using Multi-Level Configuration¶

Register workspace with agent-specific config:

kdn init --runtime podman --agent claude

Register workspace with custom project:

kdn init --runtime podman --project my-custom-project --agent goose

Note: The --agent flag is required (or set KDN_DEFAULT_AGENT environment variable) when registering a workspace.

Merging Behavior¶

Environment Variables: - Variables are merged by name - Later configurations override earlier ones - Example: If workspace sets DEBUG=false and agent sets DEBUG=true, the final value is DEBUG=true

Mount Paths: - Mounts are deduplicated by host+target pair (duplicates removed) - Order is preserved (first occurrence wins) - Example: If workspace has mounts for .gitconfig and .ssh, and global adds .ssh and .kube, the result contains .gitconfig, .ssh, and .kube

MCP Servers: - Commands and servers are each merged by name - Later configurations override earlier ones with the same name - Example: If workspace defines an MCP command named filesystem and agent config also defines filesystem, the agent config's version is used

Network: - The base (lower-precedence) network policy is dominant - If base has allow mode, the base configuration is used regardless of the override - If base has deny mode and override has allow mode, the base configuration is used (overrides cannot loosen the policy) - If both base and override have deny mode, the hosts from both are merged (deduplicated) - Example: If workspace config denies all except api.github.com and agent config allows all, the final result is deny with api.github.com allowed (workspace policy wins)

Secrets: - Secrets are deduplicated by name - First occurrence wins (base secrets take precedence); later configs only add unseen names - Order is preserved: base secrets first, then new unique secrets from overrides - Example: If workspace defines "my-github-token" and agent config also defines "my-github-token", the workspace entry is kept and the agent config entry is ignored

Configuration Files Don't Exist?¶

All multi-level configurations are optional: - If agents.json doesn't exist, agent-specific configuration is skipped - If projects.json doesn't exist, project and global configurations are skipped - If workspace.json doesn't exist, only user-specific configurations are used

The system works without any configuration files and merges only the ones that exist.

Example: Complete Multi-Level Setup¶

Workspace config (.kaiden/workspace.json - committed to git):

{
  "environment": [
    {"name": "NODE_ENV", "value": "development"}
  ]
}

Global config (~/.kdn/config/projects.json - your machine only):

{
  "": {
    "mounts": [
      {"host": "$HOME/.gitconfig", "target": "$HOME/.gitconfig"},
      {"host": "$HOME/.ssh", "target": "$HOME/.ssh"}
    ]
  }
}

Project config (~/.kdn/config/projects.json - your machine only):

{
  "https://github.com/openkaiden/kdn/": {
    "environment": [
      {"name": "DEBUG", "value": "true"}
    ]
  }
}

Agent config (~/.kdn/config/agents.json - your machine only):

{
  "claude": {
    "environment": [
      {"name": "CLAUDE_VERBOSE", "value": "true"}
    ]
  }
}

Result when running kdn init --runtime podman --agent claude: - Environment: NODE_ENV=development, DEBUG=true, CLAUDE_VERBOSE=true - Mounts: $HOME/.gitconfig, $HOME/.ssh