BoxLite review: Execution, persistence and network rules

Sixteen real BoxLite micro-VM checks cover shell results, file transfer, cross-process recovery, mount permissions, timeouts and reversible outbound allowlists.

AgentIndex · Published 2026-11-06 · Updated 2026-11-06

BoxLite is an embeddable runtime for giving an agent a Linux execution environment. Its main selection question is practical: can a job execute commands, retain useful files, recover through another caller and release its resources with explicit rules? We tested those operations in real micro-VMs on an Apple Silicon Mac.

The result supports BoxLite as a candidate for persistent local agent workspaces. Two separate Python processes opened the same box and recovered its files. Read-only mounts refused writes, command exit codes remained visible, and changing an outbound allowlist reversed which fresh HTTP connections succeeded. Adoption still requires deliberate lifecycle and file-transfer choices: temporary boxes disappear by default, and the high-level copy API does not write into a mounted /tmp.

Tested release and environment

On November 6, 2026, we installed the published Python SDK 0.11.0 into an isolated environment. The release corresponds to commit 24cef4607416b4b75e4663f966f8315a5e4773bd. We independently checked the CPython 3.12 macOS ARM64 wheel against its published SHA-256. This tests a released binary package, rather than assuming every feature on the main branch has shipped. Release, Python SDK reference

ItemActual test input
HostmacOS 26.6.2, Apple Silicon arm64
Python and SDKCPython 3.12.13, BoxLite 0.11.0
GuestLinux aarch64, Alpine 3.22.8
Per-box allocationOne CPU, 256 MiB; at most two simultaneous boxes
Image identityFixed Linux ARM64 OCI manifest digest
Runtime dataAn explicitly selected, disposable directory
Mounted dataArtificial read-only input and writable output folders

The reproduction fixture records the full wheel and image identities. It runs sixteen named checks without a fake runtime, model calls, personal files or private registry credentials. The wheel used here is tagged for macOS 14+ ARM64; other host platforms were not tested.

Commands report outcomes without deciding success for you

One command printed different lines to stdout and stderr and exited with code 7. The SDK returned all three values correctly. A caller that only sees a completed SDK call can therefore still have a failed shell operation. Agent integrations should inspect the exit code before presenting work as completed.

We created a session file, read it in another execution and supplied an explicit working directory and synthetic environment variable. Those values were honored. Two concurrent commands returned their own results without mixing output. That is a useful execution baseline, not a throughput test.

For timeout behavior, a three-second sleep received a 0.25-second execution timeout. It returned early with exit code -15; error_message was null. A subsequent command succeeded. Do not require an exception or populated diagnostic string to recognize failure. This case does not establish termination of every descendant process tree. SimpleBox execution implementation

Persistence survives the Python caller

The first worker created a named box with auto_remove=False, wrote files and stopped it. After that Python process exited, a second worker used the same explicit runtime directory and reuse_existing=True. It received the same box ID, reported that it had reused rather than created the box, and read both the session file and an imported file.

This is a stronger check than issuing two commands through one object. It establishes the selected file-recovery path across callers. It does not mean that Python variables, process memory or an interactive program resume automatically. An agent still needs to store durable task state and know which workspace to reopen.

A separate box using the default temporary lifecycle disappeared from runtime metadata after stop. The retained box survived stop and required explicit removal. After removal, the runtime listed no boxes. Our test uses the supported auto_remove compatibility option; the reference also documents the newer auto_delete control. Pin the SDK and make the retention decision explicit when integrating it.

Mount permissions and copying need separate decisions

The guest could read a synthetic input through a read-only bind. Writing to it failed with exit code 1, and the host file remained unchanged. Writing through a separate read-write bind produced the expected host-side output. Another unmounted host fixture path was absent inside the guest, as was one deliberately set host-only environment variable.

These tests establish those selected boundaries. They are not a VM-escape audit or proof that every host resource is inaccessible. A directory mounted read-write is intentionally shared, so selecting the mount is part of the application's access decision.

The public copy_in and copy_out methods round-tripped a file through /workspace with identical bytes. Copying into /tmp raised UnsupportedError identifying the mount. The SDK explains that this transfer path writes the underlying root filesystem, where a mounted directory would hide the result. File-transfer implementation and explanation

For file-based jobs, use an ordinary working directory such as /workspace for this copy API, or an explicitly shared output directory as tested here. Do not assume that a command can see a file merely because it was targeted at the same textual path through another transfer mechanism.

Network controls passed a reversible cross-check

The persistent box started with outbound networking explicitly disabled. Its public HTTP fetch failed. A second box allowed only example.com: that fetch succeeded and an example.org fetch failed.

To strengthen the attribution beyond one possibly unavailable website, we changed the live allowlist to example.org. A fresh request to that host then succeeded, and a fresh request to the formerly allowed example.com failed. The opposite results followed the policy change within the same running box.

This validates the selected outbound HTTP behavior and live update route. It does not cover TLS SNI, UDP, every IP-address form or the handling of connections already open during a change. The SDK reference documents default enabled networking when no policy is supplied; our restricted setup was explicit. Network configuration reference

Startup observations and registry dependency

In the recorded successful run, the first start() returned after 8.440 seconds with an empty runtime image cache. Creating another box from the cached image took 1.204 seconds. Reopening the retained box in the second Python process returned after 0.204 seconds, followed by successful file reads.

These are individual API-call observations on this host. The first includes image acquisition and excludes SDK installation; they are not comparable cold-machine benchmarks or workload completion times.

An earlier attempt failed while contacting Docker's public token endpoint before boot. Retrying succeeded. The incident is recorded as an acquisition dependency, without claiming a diagnosed BoxLite defect or a Docker outage. Reproducible integration needs both a fixed image identity and a plan for obtaining that image; creating a box can fail before any guest command runs.

Selection conclusion

Consider BoxLite when you need a programmatically managed local Linux workspace that retains files and gives the caller explicit control over execution and outbound access. The Python integration we tested ran real micro-VMs and did not use Docker CLI commands. The repository is Apache-2.0 licensed.

Before adopting it for a larger service, evaluate the intended host, workload, concurrency and operational lifecycle. Cloud REST behavior, fleet scheduling, adversarial containment and model-driven task quality were outside this review. For how an agent workspace handles its own profile files, see the PI-Desktop storage review. For static inspection without executing model weights, see the REA model-file review.