E2B private sandbox platform

This repository is the source of truth for the two-Mac E2B reliability lab. It uses the Go sandboxctl CLI for infrastructure control, Tart for ARM64 Linux VM lifecycle, Ansible for Linux configuration, Make for stable operator entry points, and a pinned E2B infra submodule.

Safety boundary

Git contains configuration and automation only. VM disks, snapshots, runtime data, passwords, tokens and private keys stay outside the repository.

First node

Install controller tools and initialize the repository:

make install-tools
ansible-galaxy collection install -r ansible/requirements.yml
make doctor
make init NODE=a

Create and boot the VM:

make vm-create NODE=a
make vm-start NODE=a
make wait-agent NODE=a

vm-start registers Tart as a per-user macOS launchd service, so the VM continues running after the invoking shell exits. Tart logs are written under ~/Library/Logs/e2b-private-platform/; vm-stop gracefully stops the VM and unloads the service.

The default lab transport is the Tart Guest Agent, so bootstrap and verification continue to work even when a macOS TUN/VPN client prevents host-to-guest IP traffic:

make bootstrap NODE=a
make verify NODE=a

Bootstrap also enrolls the dedicated controller SSH key and disables password-based SSH. Standard SSH remains available as the production-compatible transport when networking permits it:

make bootstrap-ssh NODE=a
make verify-ssh NODE=a

Repeat with NODE=b on the second Mac only after node A passes verification.

Web control room

Build and run the local Go/React console:

make console NODE=a

Open http://127.0.0.1:8080. The console provides:

• live CPU, memory, disk and uptime telemetry;
• VM start and graceful stop controls;
• KVM ioctl, NBD, huge-page and Docker readiness verification;
• a browser terminal transported through Tart Guest Agent rather than SSH;
• a local operator activity trail.

The current console intentionally binds to loopback and has no remote authentication. Do not expose it on a LAN or the internet. For frontend development, run make console-dev NODE=a and open http://127.0.0.1:5173.

Routine commands

make help
make vm-status NODE=a
make vm-ip NODE=a
make vm-stop NODE=a
make upstream-check
make test
make vet

The Make VM targets delegate to .bin/sandboxctl. The CLI can also be used directly when diagnosing the control layer:

make sandboxctl
.bin/sandboxctl doctor
.bin/sandboxctl vm status --name e2b-node-a

The next implementation stage is E2B's ARM64 source build and single-node sandbox lifecycle. See docs/architecture.md and the architecture decisions under docs/adr/ for the delivery gates and language boundaries.