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/kortex

# 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/kortex-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