Inside the sandbox: from nested VM to reconnectable workload
ArcBox's sandbox is the point where its shared System VM becomes a stronger workload boundary. This chapter follows a sandbox from creation to readiness, from a running command through pause or teardown, and from a live client connection to a reconnectable execution record. The goal is to make the distinction operational: a sandbox is not simply a container with a new command name, and it is not useful merely because a Firecracker process exists. Its value comes from coordinating nested virtualization, guest control, resource ownership, and workload state over time.
The nested chain has a deliberate readiness point
A sandbox begins inside the Linux System VM that ArcBox already uses for containers. The guest-side computer runtime owns the sandbox manager, while the host-side VMM owns the System VM. The manager reaches nested virtualization through a VM-driver interface, and Firecracker is the reference driver. This arrangement keeps the manager from hard-coding every VMM detail, but it does not make the requirements disappear: the selected host backend and hardware must be able to let the guest run another virtual machine.
On the documented macOS path, that means the VZ backend on Apple Silicon M3 or newer with macOS 15 or later. If nested virtualization is unavailable, the sandbox API is designed to fail fast with an explanatory precondition error instead of booting a guest that later fails in an opaque KVM path. Capability discovery is therefore part of the sandbox contract. A client can learn whether the current System VM backend supports the required boundary before creating a workload.
Once the capability exists, the sandbox manager prepares a separate microVM. The Firecracker adapter turns the sandbox specification into a kernel boot, disk, network interface, and vsock configuration. It stages the files that Firecracker must see into a per-VM jailer chroot when isolation is configured. The jailer matters for more than process naming. It gives the microVM a private area for its kernel, disks, sockets, logs, and checkpoint files, and it makes relocation of a snapshot possible without reopening the origin machine's host paths.
That last point explains a non-obvious restriction: checkpoint restore is exposed only in jailed mode. Firecracker snapshot loading reopens the drive paths recorded when the checkpoint was taken. Without a private chroot, those paths would be the original host paths shared with the source VM. A restore could then aim at the origin's disks or collide with its sockets. Refusing direct-mode restore is less convenient than accepting it, but it prevents a path-layout problem from becoming a data-corruption problem.
The sandbox also needs a guest-side control process. Each microVM receives vm-agent as its PID 1. The agent listens on a vsock port for execution requests and another for file operations. It starts commands, attaches pipes or a pseudo-terminal, forwards input and signals, and reports the final exit. It also performs the readiness handshake: after its execution and file listeners are bound, it dials a host readiness port and sends a byte. The host has pre-bound the corresponding listener, so the accepted dial-out means that the guest is serving the operations the manager needs.
This is a more meaningful readiness point than “the VMM started.” A Firecracker process can exist while the guest kernel is still booting, while the agent has not bound its listeners, or while a network interface is not ready. ArcBox's sandbox lifecycle reports STARTING until the guest agent answers. A template readiness probe can delay the later READY transition again, because an application may need to be listening on a port or passing a command check before the sandbox is useful to its caller.
Networking follows the same ownership chain.