agentkernel CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

agentkernel is a Firecracker-based microVM runtime for running AI coding agents (Claude Code, Gemini CLI, Codex, OpenCode) in true hardware-isolated sandboxes. It provides per-project isolation with sub-125ms boot times, ~25MB images, and real kernel-level isolation via KVM.

Key difference from containers: Each sandbox runs in its own virtual machine with a dedicated Linux kernel, not a shared kernel like Docker. This provides stronger isolation guarantees.

Build Commands

# Build
cargo build

# Build release
cargo build --release

# Run tests
cargo test

# Run stress test (100 VMs, requires Firecracker implementation)
cargo test --test stress_test -- --nocapture --ignored

# Quality gates (run before commits)
cargo fmt -- --check && cargo clippy -- -D warnings && cargo test

# Run the CLI
cargo run -- <command>

Building VM Images

# Build kernel (via Docker, works on macOS)
cd images/build
docker build -t agentkernel-kernel-builder -f Dockerfile.kernel-builder .
docker run --rm -v "$(pwd)/../kernel:/kernel" agentkernel-kernel-builder 6.18.45

# Output: images/kernel/vmlinux-6.18.45-agentkernel (~4MB)

Architecture

src/
├── main.rs           # CLI entry point (clap-based), command dispatch
├── config.rs         # Config parsing for agentkernel.toml
├── permissions.rs    # Security profiles and permission management
├── agents.rs         # Multi-agent support (Claude, Gemini, Codex, OpenCode)
├── ssh.rs            # SSH cert auth: CA/client keygen, sshd config, cert signing
├── http_api.rs       # HTTP REST API server (includes IP in responses)
├── mcp.rs            # MCP server for Claude Code integration
├── docker_backend.rs # Docker/Podman container backend
├── vmm.rs            # Virtual machine manager (abstracts backends)
├── languages.rs      # Language/runtime detection
└── setup.rs          # Setup and installation management

images/
├── kernel/
│   ├── microvm.config              # Minimal kernel config for Firecracker
│   └── vmlinux-*-agentkernel       # Built kernel (after build)
├── rootfs/                          # Rootfs images (TODO)
└── build/
    ├── build-kernel.sh             # Kernel build script
    └── Dockerfile.kernel-builder    # Docker build environment

tests/
└── stress_test.rs                   # 100 VM parallel stress test

plan/
└── firecracker-pivot.md            # Full architecture plan