Firecracker, QEMU, and libkrun backends

Celesto can run your sandbox with different local engines. Most users can leave the backend on auto; Celesto picks the right one for the host, guest, and image you are using.

How Celesto picks a backend

Celesto resolves the backend in this order:

Explicit argument - Celesto(backend="qemu")
Environment variable - SMOLVM_BACKEND=firecracker
Automatic default - macOS uses QEMU, Linux uses Firecracker

The supported values are auto, firecracker, qemu, and libkrun.

from celesto import Celesto

# Auto is the default.
with Celesto() as vm:
    print(vm.run("uname -a").stdout)

# Pick a backend when you need a specific runtime.
with Celesto(backend="qemu") as vm:
    print(vm.run("cat /etc/os-release").stdout)

libkrun is available as an experimental backend. Use it when you are testing libkrun specifically. Firecracker and QEMU are the stable choices for everyday sandbox work.

Choose a backend

Use this table when you know what kind of host or workload you have.

Situation	Best choice	Why
Linux production	The backend you deploy with	QEMU and Firecracker both support accelerated Linux sandboxes; choose for workload and operational fit
Linux CI	The backend you deploy with	Keeps lifecycle, networking, and performance behavior aligned with production
macOS development	`auto` or `qemu`	Firecracker needs Linux KVM; QEMU uses macOS virtualization support
Windows guests	`qemu`	Windows guest support requires QEMU
QEMU performance testing	`qemu` with `qemu_machine="auto"`	Uses QEMU’s fast `microvm` path when the guest supports it
Maximum compatibility	`qemu` with `qemu_machine="q35"`	Uses QEMU’s broader virtual hardware model
libkrun experiments	`libkrun`	Tests the libkrun runtime path directly

Comparison matrix

Capability	Firecracker	QEMU	libkrun
Linux host support	Yes, with KVM	Yes	Yes, when libkrun is installed
macOS host support	No	Yes	Yes, when libkrun is installed
Windows guest support	No	Yes	No
Default on Linux	Yes	No	No
Default on macOS	No	Yes	No
Hardware acceleration	KVM required	KVM on Linux, Hypervisor.framework on macOS	libkrun runtime
Device model	Minimal	Broad	Minimal
Snapshot and restore	Supported	Supported	Not yet supported
Pause and resume	Supported	Supported	Not yet supported
Outbound access off	Linux with vsock	Linux and macOS	Not yet supported
IPv4 destination restrictions	Linux with vsock	Linux TAP	Not yet supported
Fast vsock control channel	Supported on Linux	Supported for compatible Linux guests	Experimental
Best fit	Fast Linux sandboxes with a small device model	Linux production, macOS, Windows guests, and broad compatibility	Runtime experiments

Firecracker

Firecracker is a small virtual machine monitor built for serverless workloads. It is the default on Linux because it starts quickly, keeps virtual hardware narrow, and works well for many short-lived sandboxes.

Requirements

Linux host
KVM enabled
Firecracker binary available to Celesto
Network setup for TAP devices and nftables rules

Run setup before your first Firecracker sandbox:

celesto setup
celesto doctor --backend firecracker

Strengths

Small attack surface - Firecracker exposes a narrow set of virtual devices.
Linux production default - Celesto uses Firecracker automatically on Linux when backend="auto".
Snapshots - Firecracker supports snapshot and restore for checkpointing and resume flows.
vsock control - Recent Celesto images can use the Rust guest agent over vsock for low-latency commands.

Limits

Firecracker runs on Linux hosts with KVM.
It does not run on macOS.
It supports fewer device types than QEMU by design.
Windows guests require QEMU instead.

Use Firecracker from Python

from celesto import Celesto

with Celesto(backend="firecracker") as vm:
    result = vm.run("echo hello from firecracker")
    print(result.stdout)

Use Firecracker from the CLI

celesto sandbox create --backend firecracker --name linux-prod-test
celesto sandbox ssh linux-prod-test
celesto sandbox stop linux-prod-test

Force Firecracker for a process

export SMOLVM_BACKEND=firecracker
python my_agent.py

QEMU

QEMU is a mature, full-featured virtualizer that works across platforms. On macOS it uses Apple’s Hypervisor Framework (HVF) for near-native performance. It is also available on Linux for environments without KVM, and is the only backend for Windows guests. On Linux x86_64 direct-kernel guests, QEMU now uses its faster microvm machine model by default. You can still force the older q35 model when you need broader device compatibility.

Requirements

macOS or Linux host
QEMU binaries available to Celesto
KVM on Linux for hardware acceleration, or Hypervisor.framework on macOS

Run setup before your first QEMU sandbox:

celesto setup
celesto doctor --backend qemu

Strengths

Cross-platform host support - QEMU works on macOS and Linux.
Windows guests - Celesto uses QEMU for Windows sandbox images.
Broad compatibility - QEMU can expose more virtual hardware than Firecracker.
Fast Linux microvm path - QEMU uses microvm automatically for supported direct-kernel Linux guests.

Limits

QEMU has a larger device model than Firecracker.
Linux QEMU supports production TAP networking with per-sandbox isolation and outbound access controls.
q35 is broader but slower than the QEMU microvm path for supported Linux guests.

Use QEMU from Python

from celesto import Celesto

with Celesto(backend="qemu") as vm:
    result = vm.run("echo hello from qemu")
    print(result.stdout)

Use QEMU from the CLI

celesto sandbox create --backend qemu --name qemu-test
celesto sandbox ssh qemu-test
celesto sandbox stop qemu-test

Choose a QEMU machine

Leave qemu_machine as auto for normal use:

from celesto import Celesto

with Celesto(backend="qemu", qemu_machine="auto") as vm:
    print(vm.run("uname -m").stdout)

Force the compatibility path when you are debugging old QEMU behavior or need a broader virtual hardware model:

SMOLVM_QEMU_MACHINE=q35 celesto sandbox create --backend qemu --name q35-test

Supported values are:

Value	Behavior
`auto`	Uses `microvm` for supported Linux x86_64 direct-kernel guests, then falls back to `q35`
`microvm`	Requests QEMU’s smaller microVM hardware model
`q35`	Uses the broader compatibility hardware model

QEMU networking modes

QEMU supports two network modes through the qemu_network field on VMConfig:

Mode	Use it when
`slirp`	You want simple local networking without root privileges. This is the default for QEMU.
`tap`	You run QEMU on Linux and want a private guest IP, host isolation rules, or restricted IPv4 destinations.

Set qemu_network="tap" when you are building a custom image configuration and want Linux QEMU guests to use the host TAP path.

from pathlib import Path
from celesto import Celesto, VMConfig

config = VMConfig(
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
    backend="qemu",
    qemu_network="tap",
)

with Celesto(config) as vm:
    print(vm.run("ip -4 addr show eth0").stdout)

See network configuration for the host setup TAP mode reuses. QEMU slirp supports open access and off mode on macOS and Linux. QEMU TAP supports open, off, and restricted IPv4 destinations on Linux. In both modes, expose_local() keeps applications reachable from the host. See Network controls.

libkrun

libkrun runs Linux guests through the libkrun stack. Celesto exposes it as an experimental backend for testing the next runtime path.

SMOLVM_BACKEND=libkrun celesto sandbox create --name krun-test

libkrun does not support pause, resume, snapshots, or snapshot restore yet. Use Firecracker or QEMU when those lifecycle operations matter.

Switching backends

Per sandbox

Use this when one test or workload needs a specific runtime.

from celesto import Celesto

firecracker_vm = Celesto(backend="firecracker")
qemu_vm = Celesto(backend="qemu")

Per shell session

Use this when every sandbox launched by a script should use the same backend.

export SMOLVM_BACKEND=qemu
python my_script.py

Per application

Set the environment variable before importing Celesto.

import os

os.environ["SMOLVM_BACKEND"] = "firecracker"

from celesto import Celesto

with Celesto() as vm:
    print(vm.run("uname -a").stdout)

Native helper path

Recent Celesto releases move several hot host-side operations into the Rust smolvm-core helper package. Most users do not need to call it directly; the main celesto package uses it automatically when the matching wheel is installed. The native helpers cover:

Linux networking setup for TAP devices, routes, and sysctls
Sparse disk copy and zstd decompression for image startup
QEMU monitor control for pause, resume, and snapshots
Firecracker API socket control

Check what your install can use:

python -m smolvm_core

If a native helper is unavailable, Celesto either falls back to the slower Python or subprocess path, or reports the missing helper with a fix such as reinstalling smolvm-core.

Recommendations

For Linux production

Use the backend you run in production. Choose QEMU for QEMU lifecycle and networking parity, or Firecracker for its smaller device model. Both use hardware acceleration through KVM.

from celesto import Celesto

with Celesto(
    backend="qemu",
    memory=512,
) as vm:
    print(vm.run("echo production-like sandbox").stdout)

For QEMU CIDR restrictions on Linux, opt into TAP networking through VMConfig.qemu_network="tap". Keep the default slirp network when simple setup and open or off access are enough.

For macOS development

Use auto or qemu.

from celesto import Celesto

with Celesto(
    backend="qemu",
    memory=1024,
) as vm:
    print(vm.run("echo local development").stdout)

QEMU is the stable local backend on macOS.

For Linux CI

Use the backend you deploy with so CI covers the same machine model, lifecycle, and networking behavior as production.

steps:
  - name: Install Celesto
    run: pip install celesto

  - name: Configure host runtime
    run: celesto setup

  - name: Check backend
    run: celesto doctor --backend firecracker --strict

  - name: Run tests
    run: |
      export SMOLVM_BACKEND=firecracker
      pytest tests/

For macOS CI

Use QEMU because Firecracker is Linux-only.

steps:
  - name: Install Celesto
    run: pip install celesto

  - name: Configure host runtime
    run: celesto setup

  - name: Check backend
    run: celesto doctor --backend qemu --strict

  - name: Run tests
    run: |
      export SMOLVM_BACKEND=qemu
      pytest tests/

Diagnostics

Use celesto doctor to check backend availability before you launch sandboxes:

celesto doctor
celesto doctor --backend firecracker
celesto doctor --backend qemu
celesto doctor --backend libkrun
celesto doctor --json --strict

Troubleshooting

KVM is not available on Linux

Error: KVM support not detected

Try these checks:

Verify KVM modules: lsmod | grep kvm
Check virtualization support in your BIOS or cloud instance type.
Run host setup again: celesto setup
Run diagnostics: celesto doctor --backend firecracker --strict

QEMU is not found on macOS

Error: qemu-system-x86_64 not found

Install QEMU through setup:

celesto setup
celesto doctor --backend qemu

The wrong backend was selected

Force a backend for one command:

SMOLVM_BACKEND=firecracker python my_agent.py

Or pass the backend in code:

from celesto import Celesto

with Celesto(backend="firecracker") as vm:
    print(vm.run("uname -a").stdout)

Next steps

Control channel

See how Celesto runs commands inside a sandbox

Networking

Configure host networking and isolation

Performance

Compare boot and command latency

Troubleshooting

Fix backend and startup issues

​How Celesto picks a backend

​Choose a backend

​Comparison matrix

​Firecracker

​Requirements

​Strengths

​Limits

​Use Firecracker from Python

​Use Firecracker from the CLI

​Force Firecracker for a process

​QEMU

​Requirements

​Strengths

​Limits

​Use QEMU from Python

​Use QEMU from the CLI

​Choose a QEMU machine

​QEMU networking modes

​libkrun

​Switching backends

​Per sandbox

​Per shell session

​Per application

​Native helper path

​Recommendations

​For Linux production

​For macOS development

​For Linux CI

​For macOS CI

​Diagnostics

​Troubleshooting

​KVM is not available on Linux

​QEMU is not found on macOS

​The wrong backend was selected

​Next steps

Control channel

Networking

Performance

Troubleshooting

How Celesto picks a backend

Choose a backend

Comparison matrix

Firecracker

Requirements

Strengths

Limits

Use Firecracker from Python

Use Firecracker from the CLI

Force Firecracker for a process

QEMU

Requirements

Strengths

Limits

Use QEMU from Python

Use QEMU from the CLI

Choose a QEMU machine

QEMU networking modes

libkrun

Switching backends

Per sandbox

Per shell session

Per application

Native helper path

Recommendations

For Linux production

For macOS development

For Linux CI

For macOS CI

Diagnostics

Troubleshooting

KVM is not available on Linux

QEMU is not found on macOS

The wrong backend was selected

Next steps