Berry Wiki

SandBoxy

Properties2
tagsai, sandboxing
aliasesSandboxy

6 min read

SandBoxy

Summary

SandBoxy is Apple’s experimental example for running AI coding agents inside lightweight Linux virtual machines on Apple-silicon Macs. It demonstrates the open-source Containerization framework rather than presenting a supported standalone product.

Problem

Coding agents often need broad command access. Running them directly on a Mac exposes personal files, local services, credentials, and the host operating system. SandBoxy puts each session behind a separate Linux kernel while sharing only selected host folders.

How It Works

  • One microVM per session: Each agent runs in a lightweight virtual machine using Apple’s Virtualization framework through the Containerization Swift package.

  • Explicit file sharing: The selected workspace is mounted read-write with virtio-fs. Other folders can be mounted read-only or read-write.

  • Cached environments: SandBoxy caches the Linux kernel, startup image, agent image, and instance filesystem. Apple says warm starts can take under one second.

  • Persistent or disposable: Named instances retain changes by default. --rm discards an instance after use.

  • No background service: A single command creates and runs the environment.

Security Boundary

  • Separate kernel: The agent does not share the macOS kernel, giving a stronger boundary than an ordinary process or standard Linux container.

  • Limited host view: Host files are absent unless explicitly mounted. However, the workspace and agent configuration mounts remain accessible to the guest.

  • Read-write risk: A compromised agent can alter every read-write mounted file, just as a contractor with a key can change anything inside the rooms they were given access to.

  • Known host exposure: Apple documents that workloads can currently reach services listening on 0.0.0.0 on the host. Future packet-filter support is intended to tighten this gap.

  • Unrestricted setup phase: Package and tool installation runs with full network access on a shared network before the filtered proxy is enabled. A hostile dependency could act during this phase.

  • Virtualization is not absolute: A flaw in the framework, hypervisor, kernel, or shared-filesystem layer could weaken isolation. Apple does not claim SandBoxy is a complete security boundary.

Platforms and Agents

  • Host: macOS 26 on Apple silicon.

  • Guest: ARM64 Linux images using the Open Container Initiative image format.

  • Built-in agent: Claude Code is the only included agent definition. It starts with permission prompts disabled inside the guest.

  • Custom agents: JSON definitions in ~/.config/sandboxy/agents/ can add other command-line agents, but their compatibility is not documented.

Setup

  • Build: Clone Apple’s Containerization repository and run its release build for SandBoxy.

  • Run: Start the built-in Claude agent with .build/release/sandboxy run claude.

  • Resources: The default is four virtual CPUs and 4 GB of memory. Both can be changed.

  • Images: The default Linux kernel comes from Kata Containers. Custom kernels must be ARM64 vmlinux builds with the required virtual-device support.

Network and Credentials

  • Default runtime network: The guest has a host-only network without a direct internet route.

  • Hostname allowlist: A host HTTP CONNECT proxy permits approved destinations. Extra hostnames can be added with --allow-hosts; --no-network-filter removes this filter.

  • Application cooperation: HTTP tools use proxy environment variables. Tools that ignore them cannot use the normal internet route, but the policy is not a general per-protocol firewall.

  • Environment secrets: -e KEY forwards a host variable and -e KEY=VALUE supplies a value. The built-in Claude definition forwards ANTHROPIC_API_KEY.

  • Agent files: The built-in Claude setup can mount ~/.claude into the guest. --no-agent-mounts skips default agent mounts.

  • SSH access: --ssh-agent forwards the host SSH agent without copying private-key files. The guest can still request signatures while forwarding is enabled.

  • Data control limit: The hostname filter controls where traffic goes, not what it contains. An exposed key or mounted file could be sent to any allowed host.

Strengths

  • Strong local isolation: Each session receives its own kernel and narrowly selected host mounts.

  • Fast reuse: Cached copy-on-write filesystems reduce startup and repeated installation costs.

  • Useful controls: Read-only mounts, disposable instances, hostname rules, optional SSH forwarding, and configurable resources cover common agent needs.

  • Open implementation: The example and underlying framework use the Apache-2.0 license and can be inspected or adapted.

  • Local operation: It avoids a hosted sandbox subscription and keeps execution on the user’s Mac.

Limits

  • Experimental: Apple warns that behavior and command flags can change.

  • Narrow compatibility: It requires a new Apple-silicon Mac operating system and includes only Claude Code out of the box.

  • Documented network gap: Host services bound to all interfaces remain reachable from the guest.

  • Setup exposure: Dependency installation happens with unrestricted networking before runtime filtering begins.

  • Mounted data remains exposed: Isolation cannot protect files or credentials deliberately shared with the agent.

  • No stable SandBoxy release: SandBoxy is an example inside the larger Containerization repository, not a separately versioned product.

Activity and Maturity

Checked 2026-07-14.

  • SandBoxy added: Commit 9275f365dd55 added the example on 2026-06-03.

  • Project status: The README labels it experimental. Its directory history showed that initial addition as the latest SandBoxy-specific change checked.

  • Framework activity: Apple’s Containerization repository was pushed to on 2026-07-10 and had about 8,820 stars and 328 forks.

  • Framework versioning: The repository had a 0.37.0 tag, but no GitHub Releases entry. This version applies to the broader framework, not a supported SandBoxy release.

Best Fit

  • Good fit: Developers on current Apple-silicon Macs who want a local, inspectable microVM foundation for Claude Code or a custom command-line agent.

  • Good fit: Teams evaluating Apple’s Containerization APIs and willing to maintain their own agent definitions and security policy.

  • Poor fit: Anyone needing cross-platform support, a stable supported product, audited isolation, managed cloud capacity, or protection for host services bound to all interfaces.

Comparison

  • Versus Clawk: Both use per-session Linux microVMs, shared workspaces, and hostname-filtered proxy access. Clawk packages these ideas into a multi-agent workflow product; SandBoxy is a narrower framework example and documents a current host-service exposure.

  • Versus Apple’s container tool: SandBoxy directly demonstrates the Swift framework with agent-specific mounts, caching, credentials, and network rules. Apple’s general command-line container tool targets broader container workloads.

  • Versus Docker or dev containers: SandBoxy provides a separate guest kernel rather than sharing a Linux virtual-machine kernel among ordinary containers. It is less mature and limited to macOS 26 on Apple silicon.

  • Versus hosted sandboxes: SandBoxy avoids remote infrastructure and usage fees, but consumes local memory and processing power and leaves maintenance to the user.

Hacker News Context

In the Clawk discussion, user c0rruptbytes linked SandBoxy with the observation that many projects were adopting Linux sandboxes and that Apple had written one too. The comment offered it as a closely related implementation, not as proof of production readiness.

Direct Sources

Unknowns

  • Independent review: No independent security audit was found in the checked primary sources.

  • Non-HTTP protocols: The exact treatment of UDP, QUIC, ICMP, and unusual protocols is not fully explained by the README.

  • Host-service scope: The practical reach and planned fix for services bound to 0.0.0.0 need further testing.

  • Support commitment: Apple does not state whether SandBoxy will become a maintained product or remain an example.

  • Secret protection: No built-in redaction, scoped secret broker, or content inspection is documented.

  • Custom agents: Real-world compatibility and required allowlists for agents other than Claude Code remain unverified.

Sources

    • imported AI research note for Sandboxy.

Graph View