OperatorsBlueprint ManagerSandbox Provisioning

VM Sandbox Provisioning (Linux)

This page is the fastest safe path to run untrusted native blueprints inside the VM sandbox. The sandbox relies on cloud-hypervisor and requires KVM access plus CAP_NET_ADMIN.

If you are running container-based blueprints only, you can skip this page.

Production setup (systemd, recommended)

This is the default production path. systemd grants the capability at runtime, so you do not need to modify the binary.

  1. Verify hardware virtualization
egrep -c '(vmx|svm)' /proc/cpuinfo

The output should be greater than 0. If it is 0, enable virtualization in BIOS/UEFI.

  1. Install dependencies
sudo apt-get update
sudo apt-get install -y cloud-hypervisor qemu-utils
  1. Enable KVM access for your user
sudo usermod -aG kvm "$USER"

Log out and back in (or run newgrp kvm) so group membership applies.

  1. Create a systemd service with ambient capabilities
sudo tee /etc/systemd/system/blueprint-manager.service >/dev/null <<'EOF'
[Unit]
Description=Blueprint Manager (Tangle)
After=network.target
 
[Service]
User=blueprint
WorkingDirectory=/var/lib/blueprint
ExecStart=/usr/local/bin/cargo-tangle blueprint run \
  --protocol tangle-evm \
  --http-rpc-url ${RPC_URL} \
  --ws-rpc-url ${WS_RPC_URL} \
  --keystore-path /var/lib/blueprint/keystore \
  --settings-file /var/lib/blueprint/settings.env \
  --spawn-method vm
Restart=always
RestartSec=5
AmbientCapabilities=CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_ADMIN
NoNewPrivileges=true
 
[Install]
WantedBy=multi-user.target
EOF

Then reload and start:

sudo systemctl daemon-reload
sudo systemctl enable --now blueprint-manager
sudo systemctl status blueprint-manager

Quick start (setcap, simple but less durable)

  1. Verify hardware virtualization
egrep -c '(vmx|svm)' /proc/cpuinfo

The output should be greater than 0. If it is 0, enable virtualization in BIOS/UEFI.

  1. Install dependencies
sudo apt-get update
sudo apt-get install -y cloud-hypervisor qemu-utils libcap2-bin
  1. Enable KVM access for your user
sudo usermod -aG kvm "$USER"

Log out and back in (or run newgrp kvm) so group membership applies.

  1. Grant CAP_NET_ADMIN to the runtime binary

If you run the manager via cargo tangle, grant the capability to cargo-tangle:

BIN="$(command -v cargo-tangle)"
sudo setcap cap_net_admin+eip "$BIN"
getcap "$BIN"

If you run blueprint-manager directly, set the capability on that binary instead.

  1. Run the manager with the VM sandbox
cargo tangle blueprint run \
  --protocol tangle-evm \
  --http-rpc-url "$RPC_URL" \
  --ws-rpc-url "$WS_RPC_URL" \
  --keystore-path ./keystore \
  --settings-file ./settings.env \
  --spawn-method vm

The manager will download kernel and disk images automatically on first run.

What is CAP_NET_ADMIN and why do we need it?

CAP_NET_ADMIN is a Linux capability that lets the process manage network interfaces and firewall rules. The VM sandbox needs it to create TAP interfaces and configure nftables rules for the guest. We grant it either:

  • Via systemd AmbientCapabilities (recommended for production).
  • Via setcap on the executable (quick local setup).

Troubleshooting

  • permission denied: /dev/kvm: ensure KVM is enabled and your user is in the kvm group.
  • cloud-hypervisor not found: confirm it is installed and in PATH.
  • missing CAP_NET_ADMIN: re-run setcap on the binary you execute, or run the process with elevated privileges.
RequirementsSetup