Skip to content

Environment Variables

kdn supports environment variables for configuring default behavior.

KDN_DEFAULT_RUNTIME

Sets the default runtime to use when registering a workspace with the init command.

Usage:

export KDN_DEFAULT_RUNTIME=fake
kdn init /path/to/project --agent claude

Priority:

The runtime is determined in the following order (highest to lowest priority):

  1. --runtime flag (if specified)
  2. KDN_DEFAULT_RUNTIME environment variable (if set)
  3. Error if neither is set (runtime is required)

Example:

# Set the default runtime for the current shell session
export KDN_DEFAULT_RUNTIME=fake

# Register a workspace using the environment variable
kdn init /path/to/project --agent claude

# Override the environment variable with the flag
kdn init /path/to/another-project --agent claude --runtime podman

Notes:

  • The runtime parameter is mandatory when registering workspaces
  • If neither the flag nor the environment variable is set, the init command will fail with an error
  • Supported runtime types depend on the available runtime implementations
  • Setting this environment variable is useful for automation scripts or when you consistently use the same runtime

KDN_DEFAULT_AGENT

Sets the default agent to use when registering a workspace with the init command.

Usage:

export KDN_DEFAULT_AGENT=claude
kdn init /path/to/project --runtime podman

Priority:

The agent is determined in the following order (highest to lowest priority):

  1. --agent flag (if specified)
  2. KDN_DEFAULT_AGENT environment variable (if set)
  3. Error if neither is set (agent is required)

Example:

# Set the default agent for the current shell session
export KDN_DEFAULT_AGENT=claude

# Register a workspace using the environment variable
kdn init /path/to/project --runtime podman

# Override the environment variable with the flag
kdn init /path/to/another-project --runtime podman --agent goose

Notes:

  • The agent parameter is mandatory when registering workspaces
  • If neither the flag nor the environment variable is set, the init command will fail with an error
  • Supported agent types depend on the available agent configurations in the runtime
  • Agent names must contain only alphanumeric characters or underscores (e.g., claude, goose, my_agent)
  • Setting this environment variable is useful for automation scripts or when you consistently use the same agent

KDN_STORAGE

Sets the default storage directory where kdn stores its data files.

Usage:

export KDN_STORAGE=/custom/path/to/storage
kdn init /path/to/project --runtime podman --agent claude

Priority:

The storage directory is determined in the following order (highest to lowest priority):

  1. --storage flag (if specified)
  2. KDN_STORAGE environment variable (if set)
  3. Default: $HOME/.kdn

Example:

# Set a custom storage directory
export KDN_STORAGE=/var/lib/kaiden

# All commands will use this storage directory
kdn init /path/to/project --runtime podman --agent claude
kdn list

# Override the environment variable with the flag
kdn list --storage /tmp/kaiden-storage

KDN_INIT_AUTO_START

Automatically starts a workspace after registration when using the init command.

Usage:

export KDN_INIT_AUTO_START=1
kdn init /path/to/project --runtime podman --agent claude

Priority:

The auto-start behavior is determined in the following order (highest to lowest priority):

  1. --start flag (if specified)
  2. KDN_INIT_AUTO_START environment variable (if set to a truthy value)
  3. Default: workspace is not started automatically

Supported Values:

The environment variable accepts the following truthy values (case-insensitive): - 1 - true, True, TRUE - yes, Yes, YES

Any other value (including 0, false, no, or empty string) will not trigger auto-start.

Example:

# Set auto-start for the current shell session
export KDN_INIT_AUTO_START=1

# Register and start a workspace automatically
kdn init /path/to/project --runtime podman --agent claude
# Workspace is now running

# Override the environment variable with the flag
export KDN_INIT_AUTO_START=0
kdn init /path/to/another-project --runtime podman --agent claude --start
# Workspace is started despite env var being 0

Notes:

  • Auto-starting combines the init and start commands into a single operation
  • Useful for automation scripts where you want workspaces ready to use immediately
  • If the workspace fails to start, the registration still succeeds, but an error is returned
  • The --start flag always takes precedence over the environment variable

KDN_AUTOCOMPLETE_IGNORE_IDS

Hides workspace IDs from shell autocompletion, so only names are suggested.

By default, commands like kdn start, kdn stop, and kdn remove autocomplete both workspace IDs and names. If only one workspace exists, the shell cannot complete the argument immediately because there are two candidates (ID and name). Setting KDN_AUTOCOMPLETE_IGNORE_IDS removes IDs from the suggestions, allowing instant completion when a single workspace is registered.

Usage:

export KDN_AUTOCOMPLETE_IGNORE_IDS=1
kdn start <TAB>   # suggests names only

Supported Values:

The environment variable accepts the following truthy values (case-insensitive): - 1 - true, True, TRUE - yes, Yes, YES

Any other value (including 0, false, no, or empty string) keeps the default behaviour of suggesting both IDs and names.

Example:

# Show only names during tab-completion
export KDN_AUTOCOMPLETE_IGNORE_IDS=1
kdn start <TAB>      # completes to the workspace name immediately if only one exists
kdn stop <TAB>
kdn remove <TAB>

# Restore default behaviour (show IDs and names)
unset KDN_AUTOCOMPLETE_IGNORE_IDS