Nested virtualization recipe

Nested virtualization

A sandbox with /dev/kvm, to run a hypervisor of your own, for example Firecracker, and the microVMs it starts. The same as the sandbox recipe: briq_exec for commands, `steps` at boot. Slower to wake: every start is a cold boot, with no memory kept. Default size large (4 CPUs, 8 GB); Pro and Team plans.

sandbox

testing

Run it

briq run kvm-sandbox

briq_run({ recipe: "kvm-sandbox", wait: true })

curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "kvm-sandbox",
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "SANDBOX_HOST": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"

stack: app
services:
  sandbox:
    recipe: kvm-sandbox
    # its defaults, each a field you can set:
    # image: ghcr.io/briq-cloud/sandbox:kvm
    # size: large
    # volume: { gb: 40 }

Fields

Name	Type	Options	Default
image	string	—	"ghcr.io/briq-cloud/sandbox:kvm"
env	record	{ key: string \| { secret, value?, literal?, scope?, hosts?, locations? } }	{}
steps	object[]	—	—
cmd	string \| string[]	—	—
size	enum	pico, micro, nano, small, medium, large, xlarge	"large"
volume	object	{ gb? }	{"gb":40}
files	record	{ key: string \| { base64 } }	—

Outputs

Returned by briq_run once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

SANDBOX_HOST: sandbox.<stack>.internal
WORKDIR: /work
PORT: 8080

What it runs

Briq	Image	Ports	Size	Volume
sandbox	ghcr.io/briq-cloud/sandbox:kvm	8080	large	40 GB at /work

When to use it

Code that runs a hypervisor of your own, for example Firecracker, and the microVMs it starts.
A test suite or a build that boots VMs.
Anything the sandbox does, with /dev/kvm in it.

Step by step: Run microVMs in a KVM sandbox.

briq_run({ recipe: "kvm-sandbox" })

Tips

Same params as the sandbox: steps, env, files, cmd, volume. Boot-only secrets and the ready marker work the same way.
large by default (4 CPUs, 8 GB). xlarge (8 CPUs, 16 GB) for a full test suite or many VMs at once. Prices: pricing.
Every start is a cold boot: no memory is kept while it sleeps. A wake takes the time of a boot, and the steps run again.
Keep work on /work: the volume (40 GB by default) is kept while it sleeps. A fork copies the disk only.
The image readies /dev/kvm: the boot runs kvm-ready when the image has it, before the steps. Another image has to ready /dev/kvm itself.
Pro and Team plans: a Hobby team gets a plan_limit error.
Not everywhere: briq_catalog lists it only where /dev/kvm is available. Otherwise use the sandbox.
Test with ls -l /dev/kvm first: briq_exec with ["ls", "-l", "/dev/kvm"].