openkaiden · slemeur · Jun 24, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,20 @@
+# Kaiden Docs
+
+Documentation site for [Kaiden](https://openkaiden.ai) — built with [Docusaurus](https://docusaurus.io/) and deployed to [docs.openkaiden.ai](https://docs.openkaiden.ai).
+
+## Development
+
+```bash
+npm install
+npm run start
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Content
+
+Documentation pages live in `content/`. The sidebar structure is defined in `sidebars.ts`.
diff --git a/docs/content/ai-agents.md b/docs/content/ai-agents.md
@@ -0,0 +1,49 @@
+---
+id: ai-agents
+title: AI Agents
+sidebar_label: AI Agents
+sidebar_position: 4
+---
+
+AI coding agents are powerful — but running them directly on your machine means they operate with your full user permissions, your credentials, and unrestricted access to your filesystem and network. Kaiden changes that: every agent runs inside a secured sandbox, so you get the productivity benefits without the risk.
+
+Running an agent through Kaiden means:
+- The agent can only touch the project directory you shared with it
+- Your API keys are injected automatically — the agent never sees them
+- Network access is limited to the services you've explicitly allowed
+- Everything the agent does is logged and visible in the dashboard
+
+You keep full control of what the agent can reach, while the agent keeps full autonomy to do its job.
+
+![Coding Agents settings](assets/coding-agents.png)
+
+The **Coding Agents** section is where you manage which agents are available in Kaiden and configure their defaults. Currently, the primary configuration is setting the **default model** for each agent — the model that will be pre-selected whenever you create a new sandbox with that agent.
+
+---
+
+## Available agents
+
+| Agent | Strength |
+|---|---|
+| **Claude Code** | Long-context reasoning, large codebase analysis, refactoring |
+| **Goose** | Open-source, extensible via plugins, broad tool support |
+| **Cursor CLI** | Familiar to Cursor editor users, strong inline editing model |
+| **GitHub Copilot** | GitHub-native workflows, PR review, issue-to-code tasks |
+| **Codex** | Fast code generation and completion |
+| **OpenCode** | Lightweight open-source option, community-maintained |
+| **OpenClaw** | Autonomous task execution, works with local and cloud models |
+| **Gemini CLI** | Multimodal input, strong at Google ecosystem tasks |
+
+Click an agent's name to open its settings panel.
+
+---
+
+## Per-agent settings
+
+**Default model** — the model pre-selected for this agent when creating a new sandbox. For Claude Code, for example, you might set `claude-sonnet-4-6` as the default for everyday tasks. The model can always be changed at sandbox creation time.
+
+---
+
+## Switching agents
+
+Agents are per-sandbox. To use a different agent on the same codebase, create a new sandbox pointing to the same folder and pick the other agent. Both sandboxes can run simultaneously if you want to compare outputs.
diff --git a/docs/content/assets/coding-agents.png b/docs/content/assets/coding-agents.png
diff --git a/docs/content/assets/knowledges.png b/docs/content/assets/knowledges.png
diff --git a/docs/content/assets/mcp.png b/docs/content/assets/mcp.png
diff --git a/docs/content/assets/models-inhouse.png b/docs/content/assets/models-inhouse.png
diff --git a/docs/content/assets/models-local.png b/docs/content/assets/models-local.png
diff --git a/docs/content/assets/models-semantic.png b/docs/content/assets/models-semantic.png
diff --git a/docs/content/assets/models.png b/docs/content/assets/models.png
diff --git a/docs/content/assets/new-workspace-agent.png b/docs/content/assets/new-workspace-agent.png
diff --git a/docs/content/assets/new-workspace-filesystem.png b/docs/content/assets/new-workspace-filesystem.png
diff --git a/docs/content/assets/new-workspace-network.png b/docs/content/assets/new-workspace-network.png
diff --git a/docs/content/assets/new-workspace-tools.png b/docs/content/assets/new-workspace-tools.png
diff --git a/docs/content/assets/new-workspace.png b/docs/content/assets/new-workspace.png
diff --git a/docs/content/assets/overview.png b/docs/content/assets/overview.png
diff --git a/docs/content/assets/project-detail.png b/docs/content/assets/project-detail.png
diff --git a/docs/content/assets/projects.png b/docs/content/assets/projects.png
diff --git a/docs/content/assets/sandboxes.png b/docs/content/assets/sandboxes.png
diff --git a/docs/content/assets/secret-add.png b/docs/content/assets/secret-add.png
diff --git a/docs/content/assets/secrets.png b/docs/content/assets/secrets.png
diff --git a/docs/content/assets/settings-cli.png b/docs/content/assets/settings-cli.png
diff --git a/docs/content/assets/settings-experimental.png b/docs/content/assets/settings-experimental.png
diff --git a/docs/content/assets/settings.png b/docs/content/assets/settings.png
diff --git a/docs/content/assets/skills.png b/docs/content/assets/skills.png
diff --git a/docs/content/assets/work.png b/docs/content/assets/work.png
diff --git a/docs/content/assets/workspace-detail-full.png b/docs/content/assets/workspace-detail-full.png
diff --git a/docs/content/assets/workspace-detail.png b/docs/content/assets/workspace-detail.png
diff --git a/docs/content/core-concepts.md b/docs/content/core-concepts.md
@@ -0,0 +1,104 @@
+---
+id: core-concepts
+title: Core Concepts
+sidebar_label: Core Concepts
+sidebar_position: 2
+---
+
+This page explains the fundamental building blocks of Kaiden. Understanding these makes the rest of the application easier to navigate.
+
+---
+
+## The three layers
+
+Kaiden organises all agentic work in three layers:
+
+```
+Project  →  Sandbox  →  Session
+```
+
+### Project
+
+A **project** represents a codebase. It is the place where you define the defaults that should apply to every agent run against that codebase: which credentials are available, which network hosts can be reached, which skills and MCP servers are enabled.
+
+You create a project once. Everything you configure at the project level is inherited automatically by every sandbox and session under it.
+
+Projects live in the **Projects** sidebar view.
+
+### Sandbox
+
+A **sandbox** is a secured, persistent environment created for a project. It is the isolated container or MicroVM where agents actually run. A sandbox:
+
+- Is created once and can be stopped and restarted without losing its configuration
+- Has its own filesystem scope — the agent can only touch the project directory
+- Enforces the network policy and credentials defined by its project
+- Can host multiple concurrent sessions
+
+Think of a sandbox as a long-lived secured workspace for a project. You don't recreate it for every agent task — you start a new session inside it.
+
+Sandboxes live in the **Sandboxes** sidebar view.
+
+### Session
+
+A **session** is one agent run with a specific goal, inside a sandbox. Sessions are ephemeral: they start, the agent works, and they stop. Multiple sessions can run simultaneously inside the same sandbox.
+
+Sessions live in the **Work** sidebar view, which acts as the day-to-day cockpit showing everything running right now.
+
+---
+
+## Agents and models
+
+**Agents** and **models** are separate concepts in Kaiden.
+
+An **agent** is the coding assistant — Claude Code, Goose, Cursor CLI, and so on. It has its own CLI, its own reasoning approach, and its own way of interacting with files and tools.
+
+A **model** is the underlying language model the agent calls to generate responses — `claude-sonnet-4-6`, `gemini-2.5-pro`, a local Ollama model, and so on.
+
+One agent can use different models. You pick the agent when creating a sandbox, and the model when starting a session (or set a default per agent in the Coding Agents section).
+
+---
+
+## Configuration inheritance
+
+Settings flow from the outside in. Each layer can override the one above it.
+
+```
+Project defaults
+  └─ Sandbox (inherits project, can override)
+       └─ Session (inherits sandbox)
+```
+
+For example: a project defines an allowed network host. A sandbox inherits it. A session running in that sandbox can reach that host without any extra configuration. If a sandbox needs an additional host not in the project policy, it can add it — without changing the project defaults for other sandboxes.
+
+---
+
+## The sandbox runtime
+
+Kaiden uses **OpenShell** as the sandbox runtime. OpenShell manages the actual container or MicroVM, enforces the network policy, injects credentials, and logs security events. Kaiden talks to OpenShell through the **kdn** CLI.
+
+Two isolation modes are available:
+
+**Podman** — container-based isolation. The agent runs inside a container image (a purpose-built environment for the chosen agent) that shares the host kernel. Fast to start, low resource overhead, and sufficient for the vast majority of coding tasks: web services, scripting, cloud-native development, and most backend work.
+
+**MicroVM** — the agent gets a complete virtual machine with its own kernel and a full OS appliance, not a container image. From the agent's perspective, it has a full host to operate on. This opens up workloads that containers cannot support cleanly:
+- Building native or mobile applications that require system-level toolchains
+- Tasks that need kernel headers, kernel modules, or low-level OS access
+- Running processes that themselves need to manage containers or VMs
+- Maximum isolation from the host for high-sensitivity environments
+
+MicroVM takes longer to start and uses more resources than Podman. The right choice depends on what the agent needs to do, not just on security posture.
+
+The active runtime and its status are always visible in the bottom status bar and in **Settings → Resources**.
+
+---
+
+## Credentials and network access
+
+Kaiden uses a **deny-by-default** network model. A sandbox cannot reach any host on the internet unless it has been explicitly allowed.
+
+There are two ways a host becomes allowed:
+
+1. **Via a credential** — when you attach a secret (e.g., a GitHub token) to a sandbox, the hosts that credential needs (`api.github.com`) are automatically added to the allow list.
+2. **Via a manual rule** — you can add any host explicitly in the project's Network Policy.
+
+Credentials are never stored as plain text inside the sandbox. They are injected by the runtime as HTTP headers at the moment a request is made. The agent makes an ordinary API call; the credential handling is invisible.
diff --git a/docs/content/credentials-and-secrets.md b/docs/content/credentials-and-secrets.md
@@ -0,0 +1,81 @@
+---
+id: credentials-and-secrets
+title: Credentials & Secrets
+sidebar_label: Credentials & Secrets
+sidebar_position: 3
+---
+
+The **Secret Vault** is where you store every credential Kaiden needs to give your sandboxes authenticated access to external services.
+
+![Secret Vault](assets/secrets.png)
+
+---
+
+## How the secret store works
+
+Kaiden splits each credential into two parts stored separately:
+
+- **Metadata** — the name, host patterns, header format, and other configuration is stored in a local file (`~/.kdn/secrets.json`). This file never contains the actual secret value.
+- **Secret value** — the credential itself is stored exclusively in your **OS credential vault**: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Kaiden never writes the value to disk itself.
+
+This means your credentials are protected by the same mechanism that protects your SSH keys, browser passwords, and system credentials — the OS's own secure storage, with access controlled by your user session. Even if someone reads the `secrets.json` file, they only see metadata.
+
+---
+
+## How credentials reach the agent
+
+When you attach a credential to a sandbox, Kaiden does three things automatically:
+
+1. **Fetches the value from the OS credential vault** and creates a provider in the sandbox runtime. The agent can call the service as if it were authenticated — without ever seeing the actual key.
+2. **Adds the service's hosts** to the sandbox's network allow-list. You get access to exactly the right hosts, no more.
+3. **Injects the credential** as the appropriate HTTP header when the agent makes requests to those hosts. For GitHub, that's `Authorization: Bearer <token>`. For custom secrets, you define the format.
+
+You don't write config files. You don't set environment variables. You pick the credential in the wizard; the rest is automatic.
+
+---
+
+## Built-in integrations
+
+Kaiden ships with a pre-configured integration for **GitHub**. It knows GitHub's host patterns and authentication format — you provide your personal access token, Kaiden handles the rest.
+
+| Integration | What it grants access to |
+|---|---|
+| GitHub | `api.github.com`, `github.com` |
+
+More built-in integrations are planned for future releases. For any service not yet covered, use a generic secret (see below).
+
+---
+
+## Adding a secret
+
+Click **+ Add secret** from the Secret Vault to open the add form.
+
+![Add secret form](assets/secret-add.png)
+
+**Name** — a label for this credential (e.g., `my-github-token`, `staging-api-key`).
+
+**Value** — the actual secret. Encrypted immediately on entry; never shown again in plaintext.
+
+**Host pattern** — which hosts this credential applies to. Examples:
+- `api.github.com` — exact host
+- `*.mycompany.com` — any subdomain
+- `staging.api.example.com:8443` — host with port
+
+**Injection settings:**
+- **Path pattern** — optional: only inject on URLs matching this path (e.g., `/api/v2/*`)
+- **Header name** — the HTTP header to set (default: `Authorization`)
+- **Value format** — how to format the token (e.g., `Bearer {value}`, `token {value}`, or just `{value}`)
+
+For a GitHub personal access token, the header is `Authorization` and the format is `Bearer {value}`. Kaiden's built-in GitHub integration sets this automatically; you only fill it in for custom services.
+
+---
+
+## What the agent actually sees
+
+The agent inside the sandbox never sees your credential values. From the agent's perspective:
+
+- Network requests to `api.github.com` just work — the sandbox intercepts them and adds the correct `Authorization` header.
+- The credential value is not in any environment variable the agent can print.
+- It's not in any file on the sandbox filesystem.
+
+This means that even if the agent is compromised or tricked into leaking its environment, your credentials are not exposed.
diff --git a/docs/content/installation.md b/docs/content/installation.md
@@ -0,0 +1,75 @@
+---
+id: installation
+title: Installation
+sidebar_label: Installation
+sidebar_position: 2
+---
+
+Kaiden is a desktop application available for macOS, Windows, and Linux. The kdn and OpenShell CLI tools it depends on are downloaded and managed from inside the app — you don't install them separately.
+
+---
+
+## Download
+
+Stable releases and nightly builds are published to the [openkaiden/prereleases](https://github.com/openkaiden/prereleases/releases) repository on GitHub.
+
+| Platform | Format | Architecture |
+|---|---|---|
+| macOS | `.dmg` | Apple Silicon (arm64) |
+| Windows | `.exe` installer or portable | x64, arm64 |
+| Linux | `.flatpak` or `.tar.gz` | x64, arm64 |
+
+Download the file for your platform, open it, and follow the standard install steps for your OS.
+
+---
+
+## Prerequisites
+
+**macOS and Windows:** no prerequisites beyond Podman (see below). Kaiden bundles everything else it needs.
+
+**Linux (Flatpak):** requires Flatpak to be installed on your system. Most major distributions ship it by default or have it in their package manager.
+
+### Podman
+
+Kaiden uses **Podman** to create and manage sandboxes. It must be installed and running on your machine before you can create your first sandbox.
+
+The easiest way to get Podman on any platform is **[Podman Desktop](https://podman-desktop.io)** — a graphical application that installs and manages Podman for you. Download it from [podman-desktop.io](https://podman-desktop.io), run the installer, and Podman Desktop will handle the rest including starting the Podman machine on macOS and Windows.
+
+If you prefer a CLI-only install, Podman is also available via standard package managers:
+
+```bash
+# Fedora / RHEL
+sudo dnf install podman
+
+# macOS
+brew install podman && podman machine init && podman machine start
+```
+
+If Kaiden cannot detect a running Podman instance at launch, **Settings → Resources** will show a warning with a direct link to Podman Desktop.
+
+---
+
+## First launch
+
+On first launch, Kaiden checks for the kdn and OpenShell CLI tools. If they are not yet installed, a setup prompt guides you through installing them in one click. Their versions are visible at any time under **Settings → CLI Tools**.
+
+---
+
+## Staying up to date
+
+Kaiden checks for updates automatically. When a new version is available, you'll see a notification in the app. CLI tools (kdn and OpenShell) can be updated independently from **Settings → CLI Tools** without reinstalling the desktop app.
+
+---
+
+## Building from source
+
+If you'd like to run the latest development version:
+
+```bash
+git clone https://github.com/openkaiden/kaiden
+cd kaiden
+pnpm install
+pnpm watch
+```
+
+Requirements: Node.js 24+, pnpm 10.x.