Workspace Configuration

Each workspace can optionally include a configuration file that customizes the environment and mount behavior for that specific workspace. The configuration is stored in a workspace.json file within the workspace's configuration directory (typically .kaiden in the sources directory).

Configuration File Location¶

By default, workspace configuration is stored at:

<sources-directory>/.kaiden/workspace.json

The configuration directory (containing workspace.json) can be customized using the --workspace-configuration flag when registering a workspace with init. The flag accepts a directory path, not the file path itself.

Configuration Structure¶

The workspace.json file uses a nested JSON structure:

{
  "environment": [
    {
      "name": "DEBUG",
      "value": "true"
    },
    {
      "name": "API_KEY",
      "secret": "github-token"
    }
  ],
  "mounts": [
    {"host": "$SOURCES/../main", "target": "$SOURCES/../main"},
    {"host": "$HOME/.ssh", "target": "$HOME/.ssh"},
    {"host": "/absolute/path/to/data", "target": "/workspace/data"}
  ]
}

Environment Variables¶

Define environment variables that will be set in the workspace runtime environment.

Structure:

{
  "environment": [
    {
      "name": "VAR_NAME",
      "value": "hardcoded-value"
    },
    {
      "name": "SECRET_VAR",
      "secret": "secret-reference"
    }
  ]
}

Fields: - name (required) - Environment variable name - Must be a valid Unix environment variable name - Must start with a letter or underscore - Can contain letters, digits, and underscores - value (optional) - Hardcoded value for the variable - Mutually exclusive with secret - Empty strings are allowed - secret (optional) - Reference to a secret containing the value - Mutually exclusive with value - Cannot be empty

Validation Rules: - Variable name cannot be empty - Exactly one of value or secret must be defined - Variable names must follow Unix conventions (e.g., DEBUG, API_KEY, MY_VAR_123) - Invalid names include those starting with digits (1INVALID) or containing special characters (INVALID-NAME, INVALID@NAME)

Mount Paths¶

Configure additional directories to mount in the workspace runtime.

Structure:

{
  "mounts": [
    {"host": "$SOURCES/../main", "target": "$SOURCES/../main"},
    {"host": "$HOME/.gitconfig", "target": "$HOME/.gitconfig"},
    {"host": "/absolute/path/to/data", "target": "/workspace/data", "ro": true}
  ]
}

Fields: - host (required) - Path on the host filesystem to mount - target (required) - Path inside the container where the host path is mounted - ro (optional) - Mount as read-only (default: false)

Path Variables:

Both host and target support the following variables: - $SOURCES - Expands to the workspace sources directory on the host, or /workspace/sources in the container - $HOME - Expands to the user's home directory on the host, or /home/agent in the container

Paths can also be absolute (e.g., /absolute/path).

Validation Rules: - host and target cannot be empty - Each path must be absolute or start with $SOURCES or $HOME - $SOURCES-based container targets must not escape above /workspace - $HOME-based container targets must not escape above /home/agent

Configuration Validation¶

When you register a workspace with kdn init, the configuration is automatically validated. If workspace.json exists and contains invalid data, the registration will fail with a descriptive error message.

Example - Invalid configuration (both value and secret set):

$ kdn init /path/to/project --runtime podman --agent claude

Error: workspace configuration validation failed: invalid workspace configuration:
environment variable "API_KEY" (index 0) has both value and secret set

Example - Invalid configuration (missing host in mount):

$ kdn init /path/to/project --runtime podman --agent claude

Error: workspace configuration validation failed: invalid workspace configuration:
mount at index 0 is missing host

Configuration Examples¶

Basic environment variables:

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

Using secrets:

{
  "environment": [
    {
      "name": "API_TOKEN",
      "secret": "github-api-token"
    }
  ]
}

git worktree:

{
  "mounts": [
    {"host": "$SOURCES/../main", "target": "$SOURCES/../main"}
  ]
}

Sharing user configurations:

{
  "mounts": [
    {"host": "$HOME/.claude", "target": "$HOME/.claude"},
    {"host": "$HOME/.gitconfig", "target": "$HOME/.gitconfig"},
    {"host": "$HOME/.kube/config", "target": "$HOME/.kube/config", "ro": true}
  ]
}

Complete configuration:

{
  "environment": [
    {
      "name": "NODE_ENV",
      "value": "development"
    },
    {
      "name": "DATABASE_URL",
      "secret": "local-db-url"
    }
  ],
  "mounts": [
    {"host": "$SOURCES/../main", "target": "$SOURCES/../main"},
    {"host": "$HOME/.claude", "target": "$HOME/.claude"},
    {"host": "$HOME/.gitconfig", "target": "$HOME/.gitconfig"}
  ]
}

Notes¶

• Configuration is optional - workspaces can be registered without a workspace.json file
• The configuration file is validated only when it exists
• Validation errors are caught early during workspace registration (init command)
• All validation rules are enforced to prevent runtime errors
• The configuration model is imported from the github.com/kortex-hub/kortex-cli-api/workspace-configuration/go package for consistency across tools