BoxedClaw

A secure AI agent framework in Rust where each agent runs in its own isolated BoxLite sandbox.

Overview

BoxedClaw provides a secure architecture for running AI agents with strong isolation guarantees:

• Agent-level sandboxing: Each agent runs in its own BoxLite microVM
• Host-managed secrets: API keys never enter the sandbox - the Host makes LLM calls on behalf of agents
• Approval workflows: Sensitive operations (file deletion, shell execution) require user approval
• Volume-based file access: Files accessed through pre-configured virtiofs mounts

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Host (Trusted Zone)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │SecretManager │  │  BoxManager  │  │       Router         │  │
│  │  • API keys  │  │ • Lifecycle  │  │ • Message routing    │  │
│  │  • LLM calls │  │ • IPC bridge │  │ • Channel mapping    │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│                            │                                     │
│              ┌─────────────┼─────────────┐                      │
│              ▼             ▼             ▼                      │
│         ┌────────┐   ┌────────┐   ┌────────┐                   │
│         │ Box 1  │   │ Box 2  │   │ Box N  │                   │
│         │Agent A │   │Agent B │   │Agent N │                   │
│         └────────┘   └────────┘   └────────┘                   │
└─────────────────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     BoxLite MicroVM Sandbox                      │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                    Agent Runtime                            │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────────────┐ │ │
│  │  │   IPC    │  │  Memory  │  │        Tools             │ │ │
│  │  │  Client  │  │  Store   │  │ • file_read/write/list   │ │ │
│  │  │          │  │          │  │ • shell (needs approval) │ │ │
│  │  └──────────┘  └──────────┘  └──────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────────┘ │
│                         /workspace (virtiofs)                    │
└─────────────────────────────────────────────────────────────────┘

Trust Model

Component	Trust Level	Responsibilities
Host	Trusted	Holds API keys, makes LLM calls, manages boxes
Box	Untrusted	Runs agent logic, no direct API access
IPC	Boundary	JSON messages over stdin/stdout

Project Structure

boxedclaw/
├── Cargo.toml              # Workspace configuration
├── boxedclaw-core/         # Core types and protocol
│   ├── src/
│   │   ├── protocol.rs     # IPC messages (HostToBox, BoxToHost)
│   │   ├── types.rs        # IDs (AgentId, RequestId, etc.)
│   │   └── error.rs        # Error types
│   └── Cargo.toml
├── boxedclaw-host/         # Main process (trusted)
│   ├── src/
│   │   ├── main.rs         # Binary entry point
│   │   ├── box_manager.rs  # Box lifecycle management
│   │   ├── router.rs       # Message routing
│   │   ├── secret_manager.rs
│   │   ├── llm/            # LLM client (OpenAI)
│   │   ├── channel/        # Input channels (CLI, API)
│   │   └── approval.rs     # Approval workflows
│   └── Cargo.toml
└── boxedclaw-agent/        # Agent runtime (inside sandbox)
    ├── src/
    │   ├── main.rs         # Binary entry point
    │   ├── runtime.rs      # Agent main loop
    │   ├── ipc.rs          # IPC client
    │   ├── memory.rs       # Conversation memory
    │   └── tools/          # Built-in tools
    │       ├── file.rs     # File operations
    │       └── shell.rs    # Shell execution
    └── Cargo.toml

Installation

Prerequisites

• Rust 1.75+ (edition 2024)
• libkrun (for BoxLite sandboxing on macOS)

# macOS
brew install libkrun

Build

cargo build --release

Usage

Host Service

# Set required environment variables
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="gpt-4o-mini"  # optional, defaults to gpt-4o-mini
export BOXEDCLAW_WORKSPACE="./workspace"  # optional

# Run the host
cargo run --release -p boxedclaw-host

Agent Binary

The agent binary is designed to run inside the BoxLite sandbox:

# Run directly (for testing)
export BOXEDCLAW_AGENT_ID="test-agent"
export BOXEDCLAW_WORKSPACE="/path/to/workspace"
cargo run --release -p boxedclaw-agent

IPC Protocol

Communication between Host and Box uses line-delimited JSON over stdin/stdout:

Host → Box Messages

enum HostToBox {
    Init { agent_id, system_prompt, tools },
    UserMessage { content, metadata },
    LlmResponse { message },
    ApprovalResult { request_id, approved, reason },
    Shutdown,
}

Box → Host Messages

enum BoxToHost {
    Ready,
    LlmRequest { messages, tools },
    FinalResponse { content },
    ApprovalRequest { request_id, operation, reason },
    Error { message, code },
    Log { level, message },
}

Security Model

4-Layer Defense

1. Application Layer: Rust memory safety, type system
2. IPC Boundary: All communication through typed messages
3. BoxLite Sandbox: MicroVM isolation with virtiofs
4. Volume Isolation: Pre-configured mount points only

Sensitive Operations

Operations requiring user approval:

Operation	Example
File Delete	rm /workspace/sensitive.txt
Shell Execute	npm install
Network Request	Custom HTTP calls

Development

Run Tests

# All tests
cargo test --workspace

# Specific crate
cargo test -p boxedclaw-agent

Lint

cargo clippy --all-targets
cargo fmt --check

License

MIT

References

• BoxLite - MicroVM runtime for AI agents
• Design Document - Detailed architecture documentation