SendBox

Authenticated, VM-backed agent sandboxing on macOS and Linux.

SendBox runs AI agents through a signed, fail-closed runtime plan. Persistent sessions use Apple's Containerization on Apple silicon or Kata Containers through nerdctl/containerd on Linux. Hyperlight is an explicit Linux/KVM one-shot provider with a narrower capability set.

• File Isolation — Host visibility is limited to explicitly configured runtime mounts; state and workspace roots must be disjoint.
• Command Filtering — Deny-first semantic policy applies to the brokered top-level argv. Descendants inherit kernel containment rather than an unprovable recursive shell-policy claim.
• Network Firewall — Apple and Kata sessions route DNS and TCP CONNECT through loopback brokers backed by cgroup-v2 identity, SO_MARK, and atomic nftables rules. UDP/QUIC and direct external agent traffic are denied.
• Package Supply-chain Proxy — npm metadata and artifacts traverse an isolated trusted proxy that verifies, scans, caches, and reports verdicts before any package bytes reach the workload.
• Runtime Providers — auto selects Apple on macOS arm64 and Kata on Linux. Explicit Apple, Kata, and Hyperlight requests never fall back silently.
• Hyperlight Execution — Verified one-shot commands run in Hyperlight/Unikraft micro-VMs on Linux; unsupported persistent guest, MCP, credential, Git-guard, and restrictive-egress features are rejected.
• Credential Injection — Secrets and repository-scoped GitHub/Copilot credentials use authenticated encrypted host-to-guest envelopes. SSH keys are staged only for a trusted SSH child in an owner-only runtime directory and are removed afterward.
• Undo & Rollback — Descriptor-safe, content-addressed SHA-256 snapshots support capture, verify, restore, diff, and prune with versioned formats.
• Audit Trail — Lifecycle operations and security decisions are committed to versioned hash-chained records with Merkle summaries and externally verifiable heads.
• Native MCP Boundary — Apple and Kata guests install a root-owned stdio broker and trusted Streamable HTTP gateway with bounded framing, strict JSON-RPC validation, exact server identities, independent deny-first tool policies, filtered discovery, and one mandatory redacted audit path. See docs/mcp-inspection.md.
• Credential-free Safe Outputs — An untrusted agent can declare a bounded subset of GitHub writes through a root-owned MCP recorder. The host verifies the sealed artifact after runtime teardown and only then resolves a dedicated write token. See docs/architecture/safe-outputs.md.
• Boundary Enforcement — The host signs one immutable runtime plan before provider dispatch. The authenticated guest starts mandatory security services before workload execution and rejects session, policy, feature, or cgroup drift.
• Supply Chain Provenance — Boundary plans and reproducible guest bundles use Ed25519 signatures, versioned trust metadata, rollback floors, inventory, and SBOM evidence. Host archives and installers receive GitHub artifact attestations.
• Runtime Supervisor — Permission grants use an explicit persisted and auditable state machine with one-time, session, pattern, and permanent-deny decisions.
• VM Hardening — Dedicated service profiles apply no-new-privileges, capability removal, resource limits, and architecture-aware TSYNC seccomp.
• Devcontainer Generation — Export sandbox configurations as devcontainer specs for reproducible environments.

Production guest artifact bundles provide static-musl guest and execution binaries, strict CO-RE BPF objects, signed manifests, inventory, SBOM metadata, deterministic rootfs tarballs, and minimal scratch OCI images for Linux x86_64 and arm64. The image contains no Python, Node.js, compiler, bpftrace, or development headers.

The production BPF programs are cgroup-scoped observation only. The Apple adapter can mount their signed bundle, but activation remains guest-policy driven and these programs do not claim exec, syscall, network, or MCP enforcement.

Download the matching artifact from Releases. Verify its GitHub attestation and checksum before installing it:

gh attestation verify sendbox-<version>-<platform>.tar.gz \
  -R mbianchidev/sendbox
shasum -a 256 -c sendbox-<version>-<platform>.tar.gz.sha256

The installation guide covers tarball and macOS installation, release trust, and guest-bundle placement.

git clone https://github.com/mbianchidev/sendbox.git
cd sendbox
make install

Source installs require a separately attested signed guest bundle and trust root; tagged host artifacts already include the matching pair.

For an interactive runtime preflight and configuration flow:

./setup.sh

Kata installation and containerd configuration are documented in the Kata Containers guide.

The .pkg and .dmg are not Apple-signed or notarized. Follow the macOS package instructions rather than disabling Gatekeeper.

Generate .sendbox.yaml in the project root, then edit it as needed using the configuration guide:

sendbox init --project .
sendbox init --project . --runtime kata

# Launch one exact argv workload through a verified guest bundle
sendbox run \
  --config .sendbox.yaml \
  --runtime kata \
  --image registry.example/workload@sha256:<digest> \
  --bundle /usr/local/share/sendbox/guest/x86_64/bundle \
  --trust-root /usr/local/share/sendbox/guest/x86_64/release-public.key \
  -- /usr/bin/true

Tarball users can point these flags at guest/<architecture>/ inside the extracted release directory. A bundled public key is not self-authenticating; trust it only after verifying the host or standalone guest archive attestation.

--interactive runs terminal agents such as GitHub Copilot CLI, Claude Code, Codex, and Gemini on a pseudoterminal inside the sandbox:

sendbox run --interactive \
  --config .sendbox.yaml \
  --runtime kata \
  --image registry.example/workload@sha256:<digest> \
  --bundle /usr/local/share/sendbox/guest/x86_64/bundle \
  --trust-root /usr/local/share/sendbox/guest/x86_64/release-public.key \
  -- /usr/bin/copilot

See interactive sessions for terminal requirements, flow control, separate stderr, and troubleshooting.

Browse the documentation index for architecture, qualification, migration, and implementation-history documents.

┌─────────────┐     ┌─────────────────┐
│ sendbox CLI │────▶│ RuntimeProvider │
└─────────────┘     └────────┬────────┘
                    ┌────────┴─────────┐
                    ▼                  ▼
          Apple Containerization   nerdctl/containerd
             (macOS arm64)          + Kata shim (Linux)
                    │                  │
                    └────────┬─────────┘
                             ▼
                  Dedicated Linux guest VM

The Rust workspace separates immutable boundary planning, provider-neutral orchestration, runtime adapters, authenticated guest services, and security-record persistence. The CLI depends on native project analysis and devcontainer generation; no production path requires Node.js or Copilot.

The architecture index links to the runtime, protocol, security-boundary, and agent-tooling design documents.

SendBox follows a deny-by-default security posture:

1. Filesystem — Only explicitly configured host paths are mounted into the guest. State and workspace roots cannot overlap.
2. Commands — Deny rules win over allow rules for the brokered top-level argv. Descendants inherit the guest execution boundary rather than being recursively reinterpreted as shell text.
3. Network — Persistent workloads can reach only the loopback DNS and SOCKS5 brokers. Kernel rules deny direct external agent traffic and unmarked broker traffic.
4. Packages — Configured npm artifacts are quarantined, verified, and inspected before release.
5. Secrets — Repository, Copilot, MCP gateway, and package registry credentials use separate scopes and trusted delivery paths.
6. Isolation — Apple and Kata provide persistent Linux VMs; Hyperlight provides explicit Linux/KVM one-shot isolation.
7. Boundaries — Signed guest services must become ready before execution; unsupported transports and authorization fallback fail closed.
8. Branches — Trusted Git wrappers restrict selected-repository pushes and pulls; server-side rules remain required.

Read the complete security model for guarantees, assumptions, and defense-in-depth analysis.

See the CLI reference for subcommands, run flags, and common examples. The installed version also provides sendbox help <subcommand>.

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-change)
3. Run make lint (this also compiles every standalone fuzz workspace with its committed lockfile)
4. Run make test, make release, and make audit
5. Open a pull request

For larger changes, please open an issue first to discuss the approach.

This project is licensed under the Apache License 2.0.