Bandsox

Prerequisites

• Linux with KVM support (bare metal or nested virtualization)
• Firecracker installed at /usr/bin/firecracker
• Python 3.8+
• sudo access (required for TAP device networking)
• Vsock kernel module (virtio-vsock) in the guest kernel for fast file transfers (optional, falls back to serial)

Create a VM from a Docker image (needs python preinstalled)

vm = bs.create_vm("python:3-alpine", name="test-vm") print(f"VM started: {vm.vm_id}")

Installation

Building a local base rootfs

Build a minimal ext4 from a Docker image:

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 with bandsox init --rootfs-url ./bandsox-base.ext4.

You can also skip the base rootfs entirely -- BandSox builds per-image rootfs on demand from Docker images when you call bandsox create <image>.

Usage

Quick start

Create a VM and run Python code:

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'])  # Hello from VM!

vm.stop()

Remote server usage

If the BandSox server is already running somewhere, point the Python client at it:

```python from bandsox.core import BandSox

Python API

```python from bandsox.core import BandSox

bs = BandSox()

Docs and API reference

• Full library, CLI, and HTTP endpoint reference: docs/API.md
• Vsock migration guide: docs/VSOCK_MIGRATION.md
• Vsock restoration fix: VSOCK_RESTORATION_FIX.md
• REST base path: http://<host>:<port>/api (all endpoints require auth -- see API docs)