Sandbox

Sandbox Skill

Execute commands in secure, isolated containers using agentkernel. This provides hardware-level isolation to protect the host system from potentially dangerous operations.

When to Use This Skill

Use this skill when:

• Running untrusted or generated code
• Executing shell commands that could modify system state
• Testing code in a clean environment
• Running build/test commands that might have side effects
• Executing code from external sources
• Any operation where isolation is beneficial for security

Do NOT use this skill for:

• Simple file reads/writes (use standard tools)
• Git operations (use standard tools)
• Operations that need access to host credentials or SSH keys

Instructions

Basic Usage

Run any command in an isolated sandbox:

agentkernel run <command> [args...]

For compound commands with && or ||, wrap in sh -c:

agentkernel run sh -c 'npm install && npm test'

The runtime is auto-detected from the command:

# Python
agentkernel run python3 script.py
agentkernel run pip install package-name
agentkernel run pytest

# Node.js
agentkernel run node script.js
agentkernel run npm test
agentkernel run npx create-react-app my-app

# Rust
agentkernel run cargo build
agentkernel run cargo test

# Go
agentkernel run go build
agentkernel run go test ./...

# Ruby
agentkernel run ruby script.rb
agentkernel run bundle exec rspec

# And more: PHP, Java, C/C++, Elixir, Lua, Terraform...

Specifying an Image

Override the auto-detected image:

agentkernel run --image ubuntu:24.04 apt-get update
agentkernel run --image postgres:16-alpine psql --version

Security Profiles

Control 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

Keeping Sandboxes for Debugging

Keep the sandbox after execution:

agentkernel run --keep npm test
# Later: agentkernel sandbox remove run-<id>

Persistent Sandboxes

For longer-running work:

# Create and start
agentkernel sandbox create my-sandbox
agentkernel sandbox start my-sandbox

# Execute commands
agentkernel exec my-sandbox npm test
agentkernel exec my-sandbox python -m pytest

# Clean up
agentkernel sandbox stop my-sandbox
agentkernel sandbox remove my-sandbox

Supported Languages

Security Notes

• Sandboxes run in isolated containers (Docker or Podman)
• On Linux with KVM, Firecracker microVMs provide hardware-level isolation
• Three security profiles: permissive, moderate (default), restrictive
• Use --profile restrictive for maximum isolation (no network, read-only fs)
• Use --no-network to disable network access specifically
• Host filesystem is NOT mounted by default (use permissive profile to enable)
• Each sandbox gets a clean environment

Agent Compatibility Modes

Agentkernel supports compatibility modes for different AI agents. Each mode configures sandbox behavior optimally for that agent's needs:

# Claude Code compatibility (default for this plugin)
agentkernel run --compatibility-mode claude python3 script.py

# Codex compatibility (stricter isolation)
agentkernel run --compatibility-mode codex python3 script.py

# Gemini compatibility (Docker-style)
agentkernel run --compatibility-mode gemini python3 script.py

Or configure in agentkernel.toml:

[sandbox]
name = "my-project"

[agent]
preferred = "claude"
compatibility_mode = "claude"  # claude, codex, gemini, or native

[security]
profile = "moderate"  # Can override compatibility mode defaults

Compatibility Mode Differences

Claude mode allows: api.anthropic.com, cdn.anthropic.com, common package registries. Codex mode allows: api.openai.com, cdn.openai.com, common package registries. Gemini mode allows: *.googleapis.com, common package registries.

All modes block cloud metadata endpoints (169.254.169.254, metadata.google.internal).

MCP Server Integration

This plugin provides an MCP (Model Context Protocol) server for direct tool integration. When enabled, the following MCP tools are available:

Command Execution

File Operations

Lifecycle Management

sandbox_run Options

The sandbox_run tool accepts these parameters:

• command (required): Command to execute (array of strings)
• profile: Security profile (restrictive, moderate, permissive)
• compatibility_mode: Agent mode (native, claude, codex, gemini)
• network: Override network access (boolean)
• cwd: Working directory inside sandbox
• env: Environment variables (object)
• timeout_ms: Command timeout in milliseconds (default: 30000)

Example MCP request:

{
  "method": "tools/call",
  "params": {
    "name": "sandbox_run",
    "arguments": {
      "command": ["python3", "-c", "print('hello')"],
      "compatibility_mode": "claude",
      "timeout_ms": 60000
    }
  }
}

The MCP server starts automatically when the plugin is loaded and provides these tools via JSON-RPC over stdio.

Daemon Mode (Fast Execution)

For high-performance scenarios, agentkernel can run a daemon that maintains a pool of pre-warmed sandboxes:

# Start daemon with pre-warmed pool
agentkernel daemon start

# Check status
agentkernel daemon status  # Shows warm VMs per agent type

# Commands use warm pool automatically (~50ms vs ~500ms cold start)
agentkernel run python3 script.py

# Pre-warm for specific agent types
agentkernel daemon prewarm --mode claude

# Stop daemon
agentkernel daemon stop

The daemon supports per-agent pool configuration for optimal warm starts:

# Example daemon config (future)
[daemon]
min_warm = 3
max_warm = 5

[daemon.agents.claude]
min_warm = 2
runtime = "python"

[daemon.agents.codex]
min_warm = 1
runtime = "python"

Claude Code Permission Configuration

Agentkernel MCP tools are designed to run safely in isolated sandboxes. You can configure Claude Code's approval behavior for these tools in your project's .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__agentkernel__sandbox_run",
      "mcp__agentkernel__sandbox_exec",
      "mcp__agentkernel__sandbox_list",
      "mcp__agentkernel__sandbox_file_read"
    ],
    "ask": [
      "mcp__agentkernel__sandbox_file_write",
      "mcp__agentkernel__sandbox_create"
    ],
    "deny": []
  }
}

Tool Risk Levels

All tools run in isolated sandboxes, so even "medium" risk tools cannot affect the host system. The ask recommendations are for visibility, not security.

MCP Server Configuration

Add agentkernel to your Claude Code MCP servers:

// .mcp.json (project-level)
{
  "mcpServers": {
    "agentkernel": {
      "command": "agentkernel",
      "args": ["mcp", "server"],
      "env": {}
    }
  }
}

Or globally in ~/.claude/mcp.json:

{
  "mcpServers": {
    "agentkernel": {
      "command": "agentkernel",
      "args": ["mcp", "server"]
    }
  }
}

Headless/Automation Mode

For CI/CD or automated workflows, use the --allowedTools flag:

claude --allowedTools "mcp__agentkernel__*" "Run tests in sandbox"

Or configure in settings for persistent auto-approval of all agentkernel tools.

Error Handling

If a command fails, the sandbox is automatically cleaned up. Use --keep to preserve it for debugging:

agentkernel run --keep failing-command
# Inspect: docker exec -it agentkernel-run-<id> sh
# Clean up: agentkernel sandbox remove run-<id>