Skip to content

Getting Started

New to kdn? See the Glossary section for definitions of workspace, runtime, agent, and other key terms.

Prerequisites

  • Podman must be installed on your system. See podman.io/docs/installation for platform-specific instructions.
  • Authentication credentials are needed for cloud-based agents. Run kdn autoconf after installation to detect and configure credentials automatically from your environment, or edit ~/.kdn/config/agents.json manually. See the Scenarios section for agent-specific credential setup.

Install

Download and run the install script:

curl -sSfL https://github.com/openkaiden/kdn/releases/latest/download/install.sh | bash

Alternatively, download a pre-built archive for your platform from the latest release, extract it, and place the kdn binary somewhere on your PATH.

First Session

Initialize a workspace, start it, and open a terminal:

# Navigate to your project
cd /path/to/my-project

# (Recommended) Auto-detect and configure workspace from your environment and project:
# credentials, project language, ports
kdn autoconf

# Register a workspace.
# kdn auto-generates a workspace name from the directory name; use --name to override.
kdn init --runtime podman --agent claude

# List workspaces to see the generated name
kdn list

# Start the workspace (the name is auto-generated from the directory name, e.g. "my-project")
kdn start my-project

# Open an interactive terminal inside the workspace
kdn terminal my-project

Going Further

  • Scenarios — step-by-step guides for common setups: Claude or Goose with Vertex AI, Cursor with an API key, OpenCode with a local model, and more
  • Environment Variables — declare a preferred default runtime and agent to avoid repeating --runtime and --agent on every kdn init
  • Workspace Configuration — how to inject environment variables, mount directories, configure MCP servers, and control network access
  • Multi-Level Configuration — how global, project-specific, and agent-specific settings interact
  • Podman Runtime — configure the base container image and the tools available inside the workspace
  • Dev Container Features — a portable way to add tools to the workspace sandbox, compatible with all kdn runtimes
  • Commands — full reference for all kdn commands and flags