Run AI coding agents in secure, isolated microVMs. Sub-125ms boot times, real hardware isolation.
# Homebrew (macOS / Linux)
brew tap thrashr888/agentkernel && brew install agentkernel
# Or with the install script
curl -fsSL https://raw.githubusercontent.com/thrashr888/agentkernel/main/install.sh | sh
# Or with Cargo
cargo install agentkernel
# Then run setup to download/build required components
agentkernel setup# Run any command in an isolated sandbox (auto-detects runtime)
agentkernel run python3 -c "print('Hello from sandbox!')"
agentkernel run node -e "console.log('Hello from sandbox!')"
agentkernel run ruby -e "puts 'Hello from sandbox!'"
# Run commands in your project
agentkernel run npm test
agentkernel run cargo build
agentkernel run pytest
# Create from a template
agentkernel create my-project --template python
agentkernel start my-project
agentkernel exec my-project -- pytest
# Or auto-name from your git branch
agentkernel create --branch -B docker
# Run with a specific image
agentkernel run --image postgres:16-alpine psql --versionThe fastest way to execute code in isolation. Creates a temporary sandbox, runs your command, and cleans up automatically.
# Auto-detects the right runtime from your command
agentkernel run python3 script.py # Uses python:3.12-alpine
agentkernel run npm install # Uses node:22-alpine
agentkernel run cargo test # Uses rust:1.85-alpine
agentkernel run go build # Uses golang:1.23-alpine
# Override with explicit image
agentkernel run --image ubuntu:24.04 apt-get --version
# Keep the sandbox after execution for debugging
agentkernel run --keep npm test
# Use a config file
agentkernel run --config ./agentkernel.toml npm testagentkernel automatically selects the right Docker image based on:
- Command (for
run) - Detects from the command you're running - Project files - Detects from files in your directory
- Procfile - Parses Heroku-style Procfiles
- Config file - Uses
agentkernel.tomlif present
| Language | Project Files | Commands | Docker Image |
|---|---|---|---|
| JavaScript/TypeScript | package.json, yarn.lock, pnpm-lock.yaml |
node, npm, npx, yarn, pnpm, bun |
node:22-alpine |
| Python | pyproject.toml, requirements.txt, Pipfile |
python, python3, pip, poetry, uv |
python:3.12-alpine |
| Rust | Cargo.toml |
cargo, rustc |
rust:1.85-alpine |
| Go | go.mod |
go, gofmt |
golang:1.23-alpine |
| Ruby | Gemfile |
ruby, bundle, rails |
ruby:3.3-alpine |
| Java | pom.xml, build.gradle |
java, mvn, gradle |
eclipse-temurin:21-alpine |
| Kotlin | *.kt |
- | eclipse-temurin:21-alpine |
| C# / .NET | *.csproj, *.sln |
dotnet |
mcr.microsoft.com/dotnet/sdk:8.0 |
| C/C++ | Makefile, CMakeLists.txt |
gcc, g++, make, cmake |
gcc:14-bookworm |
| PHP | composer.json |
php, composer |
php:8.3-alpine |
| Elixir | mix.exs |
elixir, mix |
elixir:1.16-alpine |
| Lua | *.lua |
lua, luajit |
nickblah/lua:5.4-alpine |
| HCL/Terraform | *.tf, *.tfvars |
terraform |
hashicorp/terraform:1.10 |
| Shell | *.sh |
bash, sh, zsh |
alpine:3.20 |
If your project has a Procfile, agentkernel parses it to detect the runtime:
web: bundle exec rails server -p $PORT
worker: python manage.py runworkerFor longer-running work, create named sandboxes:
# Create a sandbox
agentkernel create my-project --dir .
# Create from a template with auto-expiry
agentkernel create ci-test --template node-ci --ttl 1h
# Create per-branch sandboxes (auto-named from git branch)
agentkernel create --branch -B docker
# Start it
agentkernel start my-project
# Run commands
agentkernel exec my-project -- npm test
agentkernel exec my-project -- python -m pytest
# Attach an interactive shell
agentkernel attach my-project
# Stop and remove
agentkernel stop my-project
agentkernel remove my-project
# List all sandboxes (or filter by project)
agentkernel list
agentkernel list --project my-appControl sandbox permissions with security profiles:
# Default: moderate security (network enabled, no mounts)
agentkernel run npm test
# Restrictive: no network, read-only filesystem, all capabilities dropped
agentkernel run --profile restrictive python3 script.py
# Permissive: network, mounts, environment passthrough
agentkernel run --profile permissive cargo build
# Disable network access specifically
agentkernel run --no-network curl example.com # Will fail| Profile | Network | Mount CWD | Mount Home | Pass Env | Read-only |
|---|---|---|---|---|---|
| permissive | Yes | Yes | Yes | Yes | No |
| moderate | Yes | No | No | No | No |
| restrictive | No | No | No | No | Yes |
Pre-configured sandbox environments for common use cases. 18+ built-in templates, or save your own.
# List available templates
agentkernel template list
# Create a sandbox from a template
agentkernel create my-project --template python
agentkernel create ci --template rust-ci
# Save a running sandbox as a reusable template
agentkernel template save my-sandbox --name my-custom-template
# Add/remove custom templates
agentkernel template add my-template /path/to/template.toml
agentkernel template remove my-templateBuilt-in templates include: python, node, rust, go, ruby, java, dotnet, php, elixir, c-cpp, shell, terraform, python-ci, node-ci, rust-ci, data-science, web-dev, fullstack.
Save and restore sandbox state, or tie sandbox lifecycle to agent conversations.
# Snapshots: save and restore sandbox state
agentkernel snapshot take my-sandbox --name before-upgrade
agentkernel snapshot list
agentkernel restore before-upgrade --as rollback
# Sessions: agent conversation lifecycle
agentkernel session start --name feature-x --agent claude -B docker
agentkernel session save feature-x
agentkernel session resume feature-x
agentkernel session list
agentkernel session delete feature-xChain sandboxes with data flow, or fan-out jobs across sandboxes.
# Pipelines: sequential multi-step execution with data flow
agentkernel pipeline pipeline.toml
# Parallel: run independent jobs concurrently
agentkernel parallel \
--job "lint:node:22-alpine:npx eslint ." \
--job "test:node:22-alpine:npm test" \
--job "build:rust:1.85-alpine:cargo build"Pipeline steps are defined in TOML with name, image, command, and optional input/output directories for data passing between steps.
# Secrets vault: store API keys and credentials
agentkernel secrets set ANTHROPIC_API_KEY sk-ant-...
agentkernel secrets get ANTHROPIC_API_KEY
agentkernel secrets list
agentkernel secrets delete ANTHROPIC_API_KEY
# Image cache management
agentkernel images list --all
agentkernel images pull python:3.12-alpine
agentkernel images prune
# Export/import sandbox configs
agentkernel export-config my-sandbox > my-sandbox.toml
agentkernel import-config my-sandbox.toml --as new-sandbox -B docker
# Export sandbox filesystem
agentkernel export my-sandbox -o backup.tar# Garbage collection (remove expired/stopped sandboxes)
agentkernel gc
agentkernel gc --dry-run
# Clean up everything (containers, images, cache)
agentkernel clean --all
# System diagnostics
agentkernel doctor
agentkernel stats
# Performance benchmarking
agentkernel benchmark
agentkernel benchmark --backends docker,podman
# Shell completions
agentkernel completions bash > /etc/bash_completion.d/agentkernel
agentkernel completions zsh > ~/.zfunc/_agentkernel
agentkernel completions fish > ~/.config/fish/completions/agentkernel.fishCreate agentkernel.toml in your project root:
[sandbox]
name = "my-project"
base_image = "python:3.12-alpine" # Explicit Docker image
[agent]
preferred = "claude" # claude, gemini, codex, opencode
[resources]
vcpus = 2
memory_mb = 1024
[security]
profile = "restrictive" # permissive, moderate, restrictive
network = false # Override: disable networkMost projects don't need a config file - agentkernel auto-detects everything.
Run agentkernel as an HTTP server for programmatic access:
# As a background service (recommended — survives reboots)
brew services start thrashr888/agentkernel/agentkernel
# Or run manually
agentkernel serve --host 127.0.0.1 --port 18888| Method | Path | Description |
|---|---|---|
| GET | /health |
Health check |
| POST | /run |
Run command in temporary sandbox |
| GET | /sandboxes |
List all sandboxes |
| POST | /sandboxes |
Create a sandbox |
| GET | /sandboxes/{name} |
Get sandbox info |
| DELETE | /sandboxes/{name} |
Remove sandbox |
| POST | /sandboxes/{name}/exec |
Execute command in sandbox |
# Run a command
curl -X POST http://localhost:18888/run \
-H "Content-Type: application/json" \
-d '{"command": ["python3", "-c", "print(1+1)"], "profile": "restrictive"}'
# Response: {"success": true, "data": {"output": "2\n"}}Check which AI coding agents are available:
agentkernel agentsOutput:
AGENT STATUS API KEY
---------------------------------------------
Claude Code installed set
Gemini CLI not installed missing
Codex installed set
OpenCode installed set
Official client libraries for the agentkernel HTTP API:
| SDK | Package | Install | Docs |
|---|---|---|---|
| Node.js | agentkernel |
npm install agentkernel |
Guide |
| Python | agentkernel-sdk |
pip install agentkernel-sdk |
Guide |
| Go | agentkernel |
go get github.com/thrashr888/agentkernel/sdk/golang |
Guide |
| Rust | agentkernel-sdk |
cargo add agentkernel-sdk |
Guide |
| Swift | AgentKernel |
Swift Package Manager | Guide |
import { AgentKernel } from "agentkernel";
const client = new AgentKernel();
// Run a command in a temporary sandbox
const result = await client.run(["python3", "-c", "print(1+1)"]);
console.log(result.output); // "2\n"
// Sandbox session with automatic cleanup
await using sandbox = await client.sandbox("my-session");
await sandbox.exec(["npm", "install"]);
const tests = await sandbox.exec(["npm", "test"]);All SDKs support sandbox sessions with automatic cleanup, streaming output (SSE), and configuration via environment variables or explicit options. See SDK documentation for all languages.
AI coding agents execute arbitrary code. Running them directly on your machine is risky:
- They can read/modify any file
- They can access your credentials and SSH keys
- Container escapes are a real threat
agentkernel uses Firecracker microVMs (the same tech behind AWS Lambda) to provide true hardware isolation:
| Feature | Docker | agentkernel |
|---|---|---|
| Isolation | Shared kernel | Separate kernel per VM |
| Boot time | 1-5 seconds | <125ms |
| Memory overhead | 50-100MB | <10MB |
| Escape risk | Container escapes possible | Hardware-enforced isolation |
| Platform | Backend | Status |
|---|---|---|
| Linux (x86_64, aarch64) | Firecracker microVMs | Full support |
| Linux (x86_64, aarch64) | Hyperlight Wasm | Experimental |
| macOS 26+ (Apple Silicon) | Apple Containers | Full support (VM isolation) |
| macOS (Apple Silicon, Intel) | Docker | Full support (~220ms) |
| macOS (Apple Silicon, Intel) | Podman | Full support (~300ms) |
| Kubernetes cluster | K8s Pods | Full support |
| Nomad cluster | Nomad Jobs | Full support |
On macOS, agentkernel automatically selects the best available backend:
- Apple Containers (macOS 26+) - True VM isolation, ~940ms
- Docker - Fastest container option, ~220ms
- Podman - Rootless/daemonless, ~300ms
Firecracker and Hyperlight require KVM (Linux only).
Deploy agentkernel on Kubernetes or Nomad for team and cloud environments. Sandboxes run as pods or job allocations with warm pools for fast acquisition.
# Kubernetes
agentkernel run --backend kubernetes -- python3 -c "print('hello from k8s')"
# Nomad
agentkernel run --backend nomad -- python3 -c "print('hello from nomad')"Install with Helm or Nomad Pack:
# Kubernetes (Helm)
helm install agentkernel oci://ghcr.io/thrashr888/charts/agentkernel \
--namespace agentkernel-system --create-namespace
# Nomad (job file)
curl -fsSLO https://raw.githubusercontent.com/thrashr888/agentkernel/main/deploy/nomad/agentkernel.nomad.hcl
nomad job run agentkernel.nomad.hclFeatures: warm pools, NetworkPolicy/network isolation, Kubernetes CRDs (AgentSandbox, AgentSandboxPool), configurable resource limits. See Orchestration docs for details.
Use agentkernel with your AI coding agent. The plugin install command sets up MCP server configs, skills, and commands for each agent.
agentkernel plugin install claude # Claude Code: skill + MCP config
agentkernel plugin install codex # Codex: MCP config
agentkernel plugin install gemini # Gemini CLI: MCP config
agentkernel plugin install opencode # OpenCode: TypeScript plugin
agentkernel plugin install mcp # Any MCP-compatible agent
agentkernel plugin list # Show install status| Agent | Files | How It Works |
|---|---|---|
| Claude Code | .claude/skills/agentkernel/SKILL.md, .claude/commands/sandbox.md, .mcp.json |
Skill teaches Claude when/how to sandbox. /sandbox command for explicit use. MCP server provides tools. |
| Codex | .mcp.json |
MCP server provides run_command, create_sandbox, exec_in_sandbox tools. |
| Gemini CLI | .gemini/settings.json |
MCP server provides sandbox tools via Gemini's MCP integration. |
| OpenCode | .opencode/plugins/agentkernel.ts |
TypeScript plugin auto-creates session sandboxes. Requires agentkernel serve. |
| Generic MCP | .mcp.json |
Works with any MCP-compatible agent. |
Once installed, Claude uses agentkernel for isolated execution:
/sandbox python3 -c "print('Hello from sandbox!')"
/sandbox npm test
/sandbox cargo build
| Mode | Platform | Latency | Use Case |
|---|---|---|---|
| Hyperlight Pool | Linux | <1µs | Sub-microsecond with pre-warmed runtimes (experimental) |
| Hyperlight (cold) | Linux | ~41ms | Cold start Wasm runtime |
| Daemon (warm pool) | Linux | 195ms | API/interactive - fast with full VM isolation |
| Docker | macOS | ~220ms | macOS development (fastest) |
| Podman | macOS | ~300ms | macOS development (rootless) |
| Podman | Linux | ~310ms | Linux without KVM (fastest, daemonless) |
| Docker | Linux | ~350ms | Linux without KVM |
| Firecracker (cold) | Linux | ~800ms | One-off commands |
See BENCHMARK.md for detailed benchmarks and methodology.
For the fastest execution on Linux, use daemon mode to maintain a pool of pre-warmed VMs:
# Start the daemon (pre-warms 3 VMs)
agentkernel daemon start
# Run commands (uses warm VMs - ~195ms latency)
agentkernel run echo "Hello from warm VM!"
# Check pool status
agentkernel daemon status
# Output: Pool: Warm VMs: 3, In use: 0, Min/Max: 3/5
# Stop the daemon
agentkernel daemon stopThe daemon maintains 3-5 pre-booted Firecracker VMs. Commands execute in ~195ms vs ~800ms for cold starts - a 4x speedup.
Hyperlight uses Microsoft's hypervisor-isolated micro VMs to run WebAssembly with dual-layer security (Wasm sandbox + hypervisor boundary). This provides the fastest isolation with ~68ms latency.
Requirements:
- Linux with KVM (
/dev/kvmaccessible) - Build with
--features hyperlight
# Build with Hyperlight support
cargo build --features hyperlight
# Run Wasm modules (experimental)
agentkernel run --backend hyperlight module.wasmKey differences from Firecracker:
- Runs WebAssembly modules only (not arbitrary shell commands)
- ~68ms startup vs 195ms daemon mode (2.9x faster)
- Sub-millisecond function calls after runtime is loaded
- Requires AOT-compiled Wasm modules for best performance
See BENCHMARK.md for detailed Hyperlight benchmarks.
When to use daemon mode:
- Running an API server
- Interactive development
- Many sequential commands
- Low latency requirements
When to use ephemeral mode:
- One-off commands
- Clean VM per execution
- Memory-constrained environments
- Getting Started - Your first sandbox
- Commands - Full CLI reference
- Configuration - Config file format
- Templates - Pre-configured sandbox environments
- Snapshots - Save and restore sandbox state
- Sessions - Agent session lifecycle management
- Pipelines - Multi-step sandbox pipelines
- Parallel - Concurrent job execution
- Secrets - API key and credential management
- Agents - Running Claude Code, Codex, Gemini CLI
- HTTP API - Programmatic access
- SDKs - Client libraries for Node.js, Python, Go, Rust, Swift
- Benchmarks - Performance numbers for every backend
- Comparisons - How agentkernel compares to E2B, Daytona, Docker
See the examples/ directory for language-specific configurations:
./scripts/run-examples.sh # Run all examples