BandSox is a fast, lightweight Python library and CLI for managing Firecracker microVMs. It provides a simple interface to create, manage, and interact with secure sandboxes, making it easy to run untrusted code or isolate workloads.

• Fast Boot Times: Leverages Firecracker's speed to start VMs in milliseconds.
• Docker Image Support: Create VMs directly from Docker images (requires Python 3 installed in the image).
• Snapshotting: Pause, resume, and snapshot VMs for instant restoration.
• Web Dashboard: Visual interface to manage VMs, snapshots, and view terminal sessions.
• CLI Tool: Comprehensive command-line interface for all operations.
• Python API: Easy-to-use Python library for integration into your own applications.
• File Operations: Upload, download, and manage files within the VM.
• Terminal Access: Interactive web-based terminal for running VMs.

Create a VM and run Python code in just a few seconds:

from bandsox.core import BandSox

bs = BandSox()
vm = bs.create_vm("python:3-alpine", enable_networking=False)

result = vm.exec_python_capture("print('Hello from VM!')")
print(result['stdout'])  # Output: Hello from VM!

vm.stop()

from bandsox.core import BandSox

# Initialize
bs = BandSox()

# Create a VM from a Docker image (which has python preinstalled)
vm = bs.create_vm("python:3-alpine", name="test-vm")
print(f"VM started: {vm.vm_id}")

# Execute a command
exit_code = vm.exec_command("echo Hello World > /root/hello.txt")

# Execute Python code directly in the VM (capture output)
result = vm.exec_python_capture("print('Hello World')")
print(result['stdout'])  # Output: Hello World

# Read a file
content = vm.get_file_contents("/root/hello.txt")
print(content) # Output: Hello World

# Stop the VM
vm.stop()

Start the web dashboard:

sudo python3 -m bandsox.cli serve --host 0.0.0.0 --port 8000

Visit http://localhost:8000 to access the dashboard.

BandSox includes a CLI tool bandsox (or python -m bandsox.cli).

Create a VM:

sudo python3 -m bandsox.cli create ubuntu:latest --name my-vm

Open a Terminal:

sudo python3 -m bandsox.cli terminal <vm_id>

Start the Web Dashboard:

sudo python3 -m bandsox.cli serve --host 0.0.0.0 --port 8000

Visit http://localhost:8000 to access the dashboard.

• Linux system with KVM support (bare metal or nested virtualization).
• Firecracker installed and in your PATH (/usr/bin/firecracker).
• Python 3.8+.
• sudo access (required for setting up TAP devices for networking).

Install BandSox directly using pip or uv:

# Using pip
pip install bandsox

# Using uv (faster)
uv pip install bandsox

Then initialize the required artifacts:

bandsox init --rootfs-url ./bandsox-base.ext4

1. Clone the repository:

   git clone https://github.com/HACKE-RC/Bandsox.git
   cd bandsox

2. Install dependencies:

   pip install -e .

3. Initialize required artifacts (kernel, CNI plugins, optional base rootfs):

   # Use a locally-built rootfs (see instructions below)
   bandsox init --rootfs-url ./bandsox-base.ext4

   This downloads:

   • vmlinux (Firecracker kernel)
   • CNI plugins (from the official upstream releases, e.g. https://github.com/containernetworking/plugins/releases/download/v1.5.1/cni-plugins-linux-amd64-v1.5.1.tgz) into cni/bin/ (or your chosen --cni-dir)
   • (Optional) a base rootfs .ext4 into storage/images/ when --rootfs-url is provided

   Default URLs are provided for kernel and CNI. For the rootfs, build one locally (instructions below) and point --rootfs-url to a local path (or file:// URL). Use --skip-* flags to omit specific downloads or --force to re-download.

BandSox consists of several components:

• Core (bandsox.core): High-level manager for VMs and snapshots.
• VM (bandsox.vm): Wrapper around the Firecracker process, handling configuration, network, and interaction.
• Agent (bandsox.agent): A lightweight Python agent injected into the VM to handle command execution and file operations.
• Server (bandsox.server): FastAPI-based backend for the web dashboard.

• Full library, CLI, and HTTP endpoint reference: API_DOCUMENTATION.md
• REST base path: http://<host>:<port>/api (see docs for endpoints such as /api/vms, /api/snapshots, /api/vms/{id}/terminal WebSocket)

Build a minimal ext4 from a Docker image and keep it local:

IMG=alpine:latest          # pick a base image with python if needed
OUT=bandsox-base.ext4
SIZE_MB=512                # increase for more disk
TMP=$(mktemp -d)

docker pull "$IMG"
CID=$(docker create "$IMG")
docker export "$CID" -o "$TMP/rootfs.tar"
docker rm "$CID"

dd if=/dev/zero of="$OUT" bs=1M count=$SIZE_MB
mkfs.ext4 -F "$OUT"
mkdir -p "$TMP/mnt"
sudo mount -o loop "$OUT" "$TMP/mnt"
sudo tar -xf "$TMP/rootfs.tar" -C "$TMP/mnt"

cat <<'EOF' | sudo tee "$TMP/mnt/init" >/dev/null
#!/bin/sh
export PATH=/usr/local/bin:/usr/bin:/bin:/sbin
mount -t proc proc /proc
mount -t sysfs sysfs /sys
mkdir -p /dev/pts
mount -t devpts devpts /dev/pts
P=$(command -v python3 || command -v python)
[ -z "$P" ] && exec /usr/local/bin/agent.py
exec "$P" /usr/local/bin/agent.py
EOF
sudo chmod +x "$TMP/mnt/init"

sudo mkdir -p "$TMP/mnt/usr/local/bin"
sudo cp bandsox/agent.py "$TMP/mnt/usr/local/bin/agent.py"
sudo chmod 755 "$TMP/mnt/usr/local/bin/agent.py"

sudo umount "$TMP/mnt"
sudo e2fsck -fy "$OUT"
sudo resize2fs -M "$OUT"   # optional: shrink to minimum
rm -rf "$TMP"

Use it locally with bandsox init --rootfs-url ./bandsox-base.ext4 (or file://$PWD/bandsox-base.ext4).

Alternative: skip providing a base rootfs entirely—BandSox can build per-image rootfs on demand from Docker images when you call bandsox create <image>.

• Large artifacts (ext4 rootfs images, snapshots, vmlinux, CNI binaries) are not tracked in git; bandsox init downloads them into storage/ and cni/bin/ (or a directory you pass via --cni-dir pointing at the official CNI release tarball).
• Default storage path is /var/lib/sandbox; override with BANDSOX_STORAGE or --storage when running the server.
• To pre-seed a base rootfs, build it locally and reference it via --rootfs-url file://...; otherwise, create VMs from Docker images on demand (no prebuilt rootfs needed).

The verification/ directory contains scripts to verify various functionalities:

• verify_bandsox.py: General smoke test.
• verify_file_ops.py: Tests file upload/download.
• verify_internet.py: Tests network connectivity inside the VM.

To run a verification script:

sudo python3 verification/verify_bandsox.py

Apache License 2.0