If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/superradcompany/microsandbox shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 13 active contributors
• Distributed ownership (top contributor 48% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live superradcompany/microsandbox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/superradcompany/microsandbox.

What it runs against: a local clone of superradcompany/microsandbox — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in superradcompany/microsandbox | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of superradcompany/microsandbox. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/superradcompany/microsandbox.git
#   cd microsandbox
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of superradcompany/microsandbox and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "superradcompany/microsandbox(\\.git)?\\b" \\
  && ok "origin remote is superradcompany/microsandbox" \\
  || miss "origin remote is not superradcompany/microsandbox (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "crates/microsandbox/lib.rs" \\
  && ok "crates/microsandbox/lib.rs" \\
  || miss "missing critical file: crates/microsandbox/lib.rs"
test -f "crates/agentd/lib/lib.rs" \\
  && ok "crates/agentd/lib/lib.rs" \\
  || miss "missing critical file: crates/agentd/lib/lib.rs"
test -f "crates/cli/lib/lib.rs" \\
  && ok "crates/cli/lib/lib.rs" \\
  || miss "missing critical file: crates/cli/lib/lib.rs"
test -f "crates/runtime/lib.rs" \\
  && ok "crates/runtime/lib.rs" \\
  || miss "missing critical file: crates/runtime/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/superradcompany/microsandbox"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Microsandbox is a Rust-based microVM sandbox runtime that spins up lightweight isolated VMs in milliseconds for executing untrusted code. It combines Firecracker-style hardware isolation with OCI container compatibility, enabling AI agents and applications to spawn secure, ephemeral compute environments without a centralized daemon—everything is rootless and embeddable as a library. Monorepo (Cargo workspace) with clear separation: crates/microsandbox is the main SDK, crates/agentd is the daemon binary (lib/agent.rs, lib/fs.rs, lib/network.rs, lib/session.rs), crates/runtime handles VM execution, crates/protocol defines wire formats, and crates/cli wraps CLI tools. Multiple SDK flavors in sdk/ (sdk/node-ts, sdk/python) and runnable examples/ for each language demonstrating specific features (fs-read-stream, net-secrets, snapshot-fork).

AI engineers and agents who need to safely execute arbitrary code with strong isolation guarantees; developers building agentic workflows in Rust, Python, or Node.js who want millisecond-scale sandbox provisioning without managing server infrastructure.

Actively developed and approaching production-readiness: at v0.4.5 with comprehensive test workflows (check.yml, test.yml), release automation, and pre-commit hooks in place. The codebase shows deliberate safety patterns (SECURITY.md, CONTRIBUTING.md), extensive Rust modules with error handling (crates/agentd/lib/error.rs), and TLS/networking primitives. However, pre-1.0 versioning and lack of visible GitHub stars/age data suggest it's still hardening for broader adoption.

Moderate risk: the project depends on modern Rust toolchain (edition 2024) and niche dependencies like firecracker/microVM tech (inferred from millisecond boot claims), which narrows the contributor pool. Single crate (crates/agentd) is excluded from workspace, suggesting potential build/dependency friction. No visible commit history or issue backlog in provided data, making it hard to assess responsiveness. The security-critical nature (executing untrusted code) demands high code quality, which is partially mitigated by structured error handling and TLS support.

The project is actively maintained with v0.4.5 as the latest release. Recent work spans core sandbox features (filesystem isolation, networking policies, TLS/secrets handling), multi-language SDK support, and specialized examples (root-bind, rootfs-patch, snapshot-fork for advanced use cases). The presence of heartbeat.rs, handoff.rs, and session.rs suggests active work on long-lived sandbox lifecycle and inter-process coordination.

git clone https://github.com/superradcompany/microsandbox.git
cd microsandbox
cargo build --release
cargo run --example net-basic  # Run a sample

For Python/Node SDKs, check sdk/python and sdk/node-ts with their respective package managers (uv for Python, npm for Node based on file structure).

Daily commands: Development: cargo build in repo root (workspace auto-discovers all crates). Run agentd daemon: cargo run -p agentd --bin main. Execute examples: cargo run --example <name> (e.g., cargo run --example net-basic). Full test suite: cargo test (invoked via .github/workflows/test.yml). Docker image: build via Dockerfile.agentd.

• Cargo.toml — Workspace root defining all member crates (cli, db, filesystem, runtime, protocol) and their interdependencies—essential to understand the project structure.
• crates/microsandbox/lib.rs — Core library entry point exposing the sandbox abstraction that ties together runtime, filesystem, and protocol layers.
• crates/agentd/lib/lib.rs — Agent daemon initialization and lifecycle management—the primary server-side component that runs inside sandboxes.
• crates/cli/lib/lib.rs — CLI main dispatcher and command routing—user-facing interface coordinating all sandbox operations.
• crates/runtime/lib.rs — Runtime abstraction managing sandbox lifecycle, resource limits, and container orchestration.
• crates/protocol/lib.rs — Defines IPC protocol between CLI/host and agent daemon—all cross-boundary communication contracts.
• crates/db/lib/lib.rs — Persistence layer for sandbox state, images, volumes, and metrics—all state serialization logic.

Add a new CLI command

1. Create a new command module file in crates/cli/lib/commands/ (crates/cli/lib/commands/mycommand.rs)
2. Implement command handler with signature: pub async fn handle(args: Args) -> Result<()> (crates/cli/lib/commands/mycommand.rs)
3. Register the command in the mod.rs command dispatcher (crates/cli/lib/commands/mod.rs)
4. Add the command variant to the CLI argument parser in main.rs (crates/cli/bin/main.rs)
5. Add integration test in tests/ directory validating the new command (crates/cli/tests/mycommand.rs)

Add a new filesystem operation

1. Define the operation message type in the protocol crate (crates/protocol/lib.rs)
2. Implement the handler in the agent daemon filesystem module (crates/agentd/lib/fs.rs)
3. Expose the operation through the filesystem abstraction (crates/filesystem/lib/agentd.rs)
4. Add a client-side wrapper in the CLI or runtime layer (crates/runtime/lib.rs)

Add a new sandbox metric or resource limit

1. Define the metric entity in the database schema (crates/db/lib/entity/sandbox_metric.rs)
2. Add collection logic in the agent daemon metrics handler (crates/agentd/lib/lib.rs)
3. Expose metric retrieval through the CLI metrics command (crates/cli/lib/commands/metrics.rs)
4. Add resource limit enforcement if needed in rlimit module (crates/agentd/lib/rlimit.rs)

• Rust — Type-safe systems programming for sandboxing, low-level resource management, and performance-critical IPC.
• OCI Image Format — Standard container image format enabling compatibility with existing tooling and image registries.
• SQLite (inferred from db crate) — Lightweight, embedded persistence for local sandbox state, images, and metrics without external dependencies.
• Protocol Buffers (or custom serialization) — Efficient, versioned IPC serialization between host CLI and agent daemon inside sandboxes.
• TLS + mTLS — Secure communication channels between host and agent; secret injection support.

• Single-machine deployment vs distributed orchestration

  • Why: Microsandbox targets local, per-agent sandboxes rather than cluster scheduling.
  • Consequence: Simpler deployment but limited to single-host scale; no multi-node load balancing.

• Millisecond startup with lightweight VMs vs full containers

  • Why: Optimized for AI agent latency; agents need fast, fresh isolation.
  • Consequence: Requires VM technology (likely QEMU or KVM) rather than pure OS containers; increased resource overhead per sandbox.

• Local-first architecture with optional registry support

  • Why: Emphasizes security and offline capability; registry is optional.
  • Consequence: Must manage image storage locally; requires manual pull/sync for distributed scenarios.

• Multi-tenant cluster orchestration (single-machine focus)
• Real-time stream processing (sandboxes are ephemeral agents)
• Cross-platform VM support beyond Linux KVM/QEMU (Linux-first design)
• Automatic scaling or horizontal distribution (local per-agent model)
• Network service mesh integration (simple point-to-point TLS)

1. agentd is excluded from workspace (see Cargo.toml exclude = ["crates/agentd"])—it has its own Cargo.lock and may require separate build/test steps. 2. Edition 2024 is a bleeding-edge Rust edition; ensure your toolchain is up-to-date (rustup update). 3. Rootless VMs require specific kernel capabilities (CAP_SYS_ADMIN, CAP_NET_ADMIN implied)—local development may fail in containers without --privileged or capability grants. 4. OCI image pulling requires network/registry access—examples download container images; ensure Docker daemon or OCI runtime is configured. 5. Firecracker/microVM binary dependency is not explicit in Cargo.toml but likely bundled or expected at runtime—check DEVELOPMENT.md for setup.

• microVM (Firecracker-style) — Microsandbox's core isolation primitive—provides hardware-level separation with minimal overhead, enabling sub-100ms boot times; understanding microVM architecture explains why sandboxes are fast and isolated
• OCI (Open Container Initiative) Images — Sandboxes run standard OCI-compliant container images; knowing OCI layer format, rootfs structure, and image manifests is essential for patching, mounting, and debugging containerized workloads
• Rootless Containerization — Microsandbox runs without root privileges via user namespaces and capability restrictions; this is critical for security and deployment safety, requiring understanding of Linux security boundaries
• Network Policy Enforcement (eBPF/netfilter implied) — crates/agentd/lib/network.rs implements firewall rules and DNS filtering for sandboxes; understanding packet filtering and policy application is key to secure multi-tenant execution
• Secret Injection & Unexploitable Secrets — Microsandbox's TLS-based secret delivery (crates/agentd/lib/tls.rs) prevents secrets from entering VM memory; grasping this pattern is essential for secure credential handling in sandboxed agents
• Async/Await & Tokio Runtime — The entire daemon (lib/heartbeat.rs, lib/session.rs) is async-Tokio based; Rust developers must understand async patterns for contributing to sandbox lifecycle management
• CBOR Serialization — crates/protocol uses CBOR (ciborium crate) for compact wire-format encoding; this enables efficient cross-language communication between SDKs and ensures payload size efficiency

• firecracker-microvm/firecracker — The underlying microVM technology powering Microsandbox's hardware isolation and sub-100ms boot times
• opencontainers/image-spec — OCI image format standard that Microsandbox uses for container compatibility (oci-client, oci-spec crates)
• superradcompany/skills — AI agent skills library referenced in README as companion to Microsandbox—agents use skills to create sandboxes
• superradcompany/microsandbox-mcp — Model Context Protocol server for Microsandbox—enables Claude and other AI agents to spawn sandboxes via MCP
• bytecodealliance/wasmtime — Alternative lightweight isolation technology (WebAssembly) for scenarios where microVMs are overkill

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CLI commands in crates/cli/lib/commands/

The CLI crate has 12+ command modules (create, exec, run, pull, etc.) but there's no visible integration test suite. Given that microsandbox is a sandbox orchestration tool, end-to-end testing of CLI workflows (create → run → remove, pull → inspect, etc.) is critical for reliability. This prevents regressions in user-facing functionality.

• [ ] Create crates/cli/tests/ directory with integration test structure
• [ ] Add test fixtures for mock sandbox configs in crates/cli/tests/fixtures/
• [ ] Write integration tests covering: create + run workflow, pull + inspect workflow, remove cleanup
• [ ] Add test helper in crates/cli/lib/ to mock agentd responses and filesystem operations
• [ ] Update GitHub workflow (.github/workflows/test.yml) to run CLI integration tests separately

Add protocol buffer or serialization benchmarks in benchmarks/

The repo has filesystem benchmarks (bench_fs.py, bench_fsmeta.py) but no benchmarks for the protocol serialization layer (crates/protocol/). Since microsandbox communicates between CLI and agentd extensively, benchmarking serialization performance (ciborium, handoff messages in crates/agentd/lib/serial.rs) would catch performance regressions and inform optimization decisions.

• [ ] Create benchmarks/bench_protocol.py using Python's timeit or criterion equivalents
• [ ] Add Rust benchmark in crates/protocol/benches/ using criterion crate for serialization methods
• [ ] Benchmark key message types: session creation, exec requests, file operations
• [ ] Document baseline metrics in benchmarks/README.md with hardware specs
• [ ] Add benchmark comparison to PR template for protocol changes

Add Python and Node.js SDK integration tests with pytest and Jest

The workspace includes SDK directories (sdk/python, sdk/node-ts) but no visible test files in the file structure. Given these are client libraries for the core system, they need regression tests. This ensures SDK users don't hit breakages when core changes, and improves adoption confidence.

• [ ] Create sdk/python/tests/ with pytest structure (conftest.py for test fixtures, e.g., mock agentd server)
• [ ] Add basic test cases: create sandbox, execute command, cleanup lifecycle
• [ ] Create sdk/node-ts/tests/ with Jest configuration (jest.config.js, test helpers)
• [ ] Write Node SDK tests mirroring Python test coverage
• [ ] Add GitHub workflow (.github/workflows/sdk-test.yml) to run both SDK test suites on push/PR

• Add integration tests for crates/agentd/lib/fs.rs covering rootfs-patch and volume-bind scenarios—currently only benchmarks exist (benchmarks/bench_fs.py); Rust tests are missing from the lib directory.
• Document the handoff protocol in crates/agentd/lib/handoff.rs with inline examples—this feature enables long-lived sessions but lacks usage examples beyond examples/rust/init-handoff/.
• Write Python SDK tests for secret injection (mirror of net-secrets example in Rust)—sdk/python exists but examples/python/ is absent for the unexploitable secrets feature.

• High · Incomplete Dependency List in Cargo.toml — Cargo.toml (workspace.dependencies section). The provided Cargo.toml workspace dependencies are truncated mid-definition at the reqwest dependency. This prevents complete analysis of all transitive dependencies and their known vulnerabilities. The file shows reqwest = { version = "0.13", without closure, indicating either formatting issues or incomplete data. Fix: Ensure the complete Cargo.toml is provided for analysis. Run cargo audit locally to identify any known CVEs in dependencies. Consider using cargo-deny for additional supply chain security checks.
• High · Use of Pre-release Hickory DNS Dependencies — Cargo.toml (workspace.dependencies: hickory-client, hickory-proto, hickory-resolver). The codebase uses pre-release versions of hickory DNS libraries (0.26.0-alpha.1): hickory-client, hickory-proto, and hickory-resolver. Pre-release versions may contain unpatched vulnerabilities and are not recommended for production use in security-critical components like DNS resolution. Fix: Upgrade to stable releases of hickory DNS libraries once available. If pre-release versions are necessary, implement additional validation and consider pinning to a specific commit hash with documented justification.
• Medium · Potential Unsafe Dependencies for Sandbox Implementation — Cargo.toml (workspace.dependencies: libc, nix). The codebase includes low-level system access libraries (libc, nix) which are essential for sandbox implementation but require careful usage. The 'nix' crate (v0.30) and 'libc' (v0.2) provide raw syscall access that could lead to privilege escalation or sandbox escape if misused. Fix: Implement strict code review processes for all nix and libc usage. Conduct regular security audits of sandbox boundary code. Consider using safe wrappers and abstractions rather than raw syscalls where possible.
• Medium · Network-Facing Dependencies Without Clear Validation — Cargo.toml (workspace.dependencies: reqwest, hickory-*, etherparse) and crates/cli/lib/net_rule.rs, crates/agentd/lib/network.rs. Multiple network-related dependencies are present (reqwest, hickory DNS, etherparse) which handle untrusted network data. The file structure shows network policy implementations, but without viewing the actual code, potential deserialization attacks or protocol parsing vulnerabilities cannot be ruled out. Fix: Implement strict input validation for all network data. Use secure deserialization libraries and validate protocol compliance. Add fuzzing tests for network parsing code, particularly in network.rs and net_rule.rs.
• Medium · Serialization with ciborium Without Clear Bounds Checking — Cargo.toml (workspace.dependencies: ciborium) and crates/agentd/lib/handoff.rs, crates/protocol crate. The codebase uses ciborium (0.2) for CBOR serialization. Without viewing the implementation, there's potential risk of denial-of-service through deeply nested or malformed CBOR payloads, especially in agent handoff or protocol serialization. Fix: Implement size limits and depth limits for deserialization. Use ciborium with configured limits. Validate all deserialized data before use. Add tests with malformed CBOR payloads.
• Medium · File System Operations Risk in Sandboxed Context — crates/agentd/lib/fs.rs, crates/filesystem crate, Cargo.toml (reflink-copy, astral-tokio-tar). The filesystem operations module (crates/filesystem and crates/agentd/lib/fs.rs) combined with reflink-copy and tar operations could be vulnerable to path traversal, symlink attacks, or TOCTOU race conditions if not properly validated. Fix: Implement strict path validation and canonicalization. Disable symlink following in tar extraction. Use secure temporary file handling. Implement proper TOCTOU guards for file operations.
• Medium · Missing Security Headers and TLS Configuration Verification — ``. While crates/agentd/lib/tls.rs exists, the Cargo.toml file structure suggests TLS implementation without visible evidence of security-best-practice headers (HSTS, CSP, etc.) or certificate pinning in the provided context. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.