How to choose an AI agent sandbox

Start with the failure you must prevent

Do not choose from the tier name alone. Decide which failure is unacceptable, then select the first tier that prevents it.

Workspace separates Git state; it does not sandbox code

workspace gives the agent a separate worktree, branch, index, and pinned base. It prevents ordinary checkout collisions and makes the final diff easy to review.

The process still runs as the host user. It can reach the user's files, credentials, sockets, and network. Use this tier only when checkout separation is the entire requirement.

Process restricts ordinary coding workloads

process confines the agent and its descendants with filesystem allowlists, syscall restrictions, namespaces, and supported resource limits. On Linux, h5i uses Landlock and seccomp. Package scripts, compiler helpers, and test workers inherit the same restrictions.

This is the practical choice for routine agent work when the main risks are unwanted file access, dangerous syscalls, or runaway subprocesses. It still shares the host kernel. Its network policy is coarse: deny networking or use the host network.

Supervised blocks raw off-list network traffic

supervised adds a private network namespace, pinned DNS results, nftables rules, and a gate on socket creation. A process cannot bypass the allowlist by clearing proxy variables and opening a raw connection.

Choose it when destination control matters more than long-lived services. The tier currently cannot keep a resident browser or dev server alive after the supervising command exits, and it still shares the host kernel.

Container provides a fixed toolchain image

container runs a prepared OCI image with rootless Podman, dropped capabilities, a read-only root filesystem, and only the intended mounts. It is useful when developers and CI must use the same operating-system packages and toolchain.

Its destination allowlist uses an HTTP/HTTPS proxy. Package managers and HTTP clients that respect the proxy are constrained; a program that opens a raw socket can bypass that route. Choose this tier for image portability, not packet-level egress enforcement.

MicroVM provides a separate guest kernel

microvm runs the workload behind a guest kernel and hypervisor. Choose it for hostile native code or any task where a shared host kernel is outside the risk budget.

It requires compatible hardware virtualization, a working microVM runtime, and a prepared image. Startup is heavier, some host credential routes are unavailable, and denied-network evidence is less detailed than proxy logs. On Linux today, it is also the tier that can keep a resident browser while enforcing network destinations outside that browser.

Verify the selected tier on the actual host

Operating-system features may exist but be unusable because of kernel configuration, permissions, or another security policy. h5i therefore probes functionality and refuses an explicit tier instead of silently downgrading it.

$ h5i box probe
$ h5i box create review-1234 --profile agent-claude --isolation supervised
$ h5i box status review-1234

probe reports what the host can run. status reports what this box actually received. Check both when filesystem, network, resource, or kernel isolation affects the decision.

Platform limits still apply

Linux and macOS do not provide identical enforcement. Linux supplies Landlock, seccomp, network namespaces, nftables, and cgroups. macOS uses Seatbelt and lacks equivalents for some network and resource controls. h5i reports unsupported controls instead of presenting them as active.

Sources and further reading

• The isolation-tier reference, including platform-specific limits.
• Write a box policy, for storing the chosen controls in the repository.
• Why sandbox the entire AI agent workload, for the motivation behind using one boundary.

Questions that come up