Firecracker is a low-level interface for interacting with Firecracker VMs.

This library is intentionally low-level and makes few deviations from the API surface exposed by Firecracker. If you are looking for a simpler, higher-level VM orchestrator, stay tuned.

Overview

Firecracker lets you create VMs programmatically. You start by creating a new VM struct with Firecracker.new/1:

vm = Firecracker.new()

This creates a %Firecracker{} struct which is meant to be an Elixir representation of a Firecracker VM.

You can configure the VM by manipulating the data structure with the various helper functions. Options are configurable via Firecracker.set_option/3:

vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")

Options represent Firecracker "process" options and are mostly one-to-one to the binary CLI arguments. Detailed VM configuration options can be configured via Firecracker.configure/3 or Firecracker.add/4.

Firecracker.configure/3 lets you configure VM-specific settings. For example, you can configure the machine configuration:

vm =
  Firecracker.new()
  |> Firecracker.configure(:machine_config, vcpu_count: 3)

Firecracker.add/4 lets you add VM devices such as drives, network interfaces or persistent memory devices:

vm =
  Firecracker.new()
  |> Firecracker.add(:drive, "root", is_root_device: true)

VM configurations map directly to the VM configurations present in the Firecracker API. See the respective module documentation for per-resource options:

• Firecracker.Balloon
• Firecracker.BootSource
• Firecracker.CpuConfig
• Firecracker.Drive
• Firecracker.Entropy
• Firecracker.Logger
• Firecracker.MachineConfig
• Firecracker.MmdsConfig
• Firecracker.NetworkInterface
• Firecracker.Pmem
• Firecracker.Serial
• Firecracker.Vsock

Prerequisites

Before you can use this library, you should ensure you have the Firecracker binary and jailer binary downloaded on your system. You can download all of the Firecracker project binaries with the mix task:

mix firecracker.install

This will download the latest Firecracker binaries for your system architecture to $HOME/.firecracker/bin.

Starting Firecracker VMs

Calling Firecracker.new/1 does not actually start a Firecracker process. The struct representation is data-only up until the point you call Firecracker.start/1:

vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.start()

After starting, you'll notice the struct state changes from :initial to :started and has an attached PID. This PID represents the externally running Firecracker process. It's important to note that this library does not do any automatic cleanup. Failure to call Firecracker.stop/1 on created VMs will result in zombie processes.

Firecracker.start/1 simply starts the Firecracker process. To boot the actual VM you must call Firecracker.boot/1. In order to boot, you need to configure the VM with a kernel image and rootfs:

vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.configure(:boot_source, kernel_image_path: kernel)
  |> Firecracker.add(:drive, "rootfs",
    path_on_host: rootfs,
    is_root_device: true,
    is_read_only: false
  )
  |> Firecracker.start()
  |> Firecracker.boot()

After booting a VM, you can pause the VM:

vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.configure(:boot_source, kernel_image_path: kernel)
  |> Firecracker.add(:drive, "rootfs",
    path_on_host: rootfs,
    is_root_device: true,
    is_read_only: false
  )
  |> Firecracker.start()
  |> Firecracker.boot()

paused = Firecracker.pause(vm)

Or shutdown the VM:

vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.configure(:boot_source, kernel_image_path: kernel)
  |> Firecracker.add(:drive, "rootfs",
    path_on_host: rootfs,
    is_root_device: true,
    is_read_only: false
  )
  |> Firecracker.start()
  |> Firecracker.boot()

shutdown = Firecracker.shutdown(vm)

Note that shutting down the VM does not kill the Firecracker process. To stop the running process, you must use Firecracker.stop/1:

vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.configure(:boot_source, kernel_image_path: kernel)
  |> Firecracker.add(:drive, "rootfs",
    path_on_host: rootfs,
    is_root_device: true,
    is_read_only: false
  )
  |> Firecracker.start()
  |> Firecracker.boot()

Firecracker.stop(vm)

Firecracker.stop/1 will ensure all of the resources associated with the VM are cleaned up properly. Internally, Firecracker.stop/1 sends SIGTERM to the running process, waits for the process to exit, and then cleans up all created sockets. The returned VM will be in an :exited state and cannot be restarted.

Applying configuration changes

At any point after a VM has been started, you can change a VM's configuration options and re-apply them to the VM using Firecracker.apply/1. Configuration changes via functions like Firecracker.configure/3 and Firecracker.add/4 are data only until they have been properly applied:

vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.configure(:boot_source, kernel_image_path: kernel)
  |> Firecracker.start()

# change the kernel and add a rootfs after start
vm =
  Firecracker.new()
  |> Firecracker.configure(:boot_source, kernel_image_path: new_kernel)
  |> Firecracker.add(:drive, "rootfs",
    path_on_host: rootfs,
    is_root_device: true,
    is_read_only: false
  )

# apply the changes
vm = Firecracker.apply(vm)

You can inspect what configuration changes will be applied by using Firecracker.dry_run/1

IO.inspect Firecracker.dry_run(vm)

# will show a configuration object
%{config: "vsock" => %{"guest_cid" => 3, "uds_path" => "/tmp/vsock.sock"}}

The Firecracker data structure keeps track of which configurations have changed since the last persisted update, and will only make the changes necessary.

Note that some changes are valid only pre-boot. If you attempt to make a change which is invalid after a VM is in a booted state, the update will fail.

Jailer

You can configure the VM to run within the Firecracker Jailer for enhanced security and resource isolation. The jailer provides sandboxing by switching to a non-root user, constraining the microVM to a chroot environment, and optionally setting up cgroups and resource limits.

To use the jailer, you must configure it before starting the VM. The uid and gid options are required:

vm =
  Firecracker.new()
  |> Firecracker.jail(uid: 1000, gid: 1000)
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.start()

You can optionally specify additional jailer configuration:

vm =
  Firecracker.new()
  |> Firecracker.jail(
    uid: 1000,
    gid: 1000,
    chroot_base_dir: "/srv/myjailer",
    netns: "/var/run/netns/custom-ns",
    parent_cgroup: "custom.slice"
  )

Configuring cgroups

Once a jailer is configured, you can set cgroup constraints:

vm =
  Firecracker.new()
  |> Firecracker.jail(uid: 1000, gid: 1000)
  |> Firecracker.cgroup("memory.limit_in_bytes", "512M")
  |> Firecracker.cgroup("cpu.cfs_quota_us", "100000")

Configuring resource limits

You can also set resource limits for the jailed process:

vm =
  Firecracker.new()
  |> Firecracker.jail(uid: 1000, gid: 1000)
  |> Firecracker.resource_limit("fsize", 1024 * 1024 * 1024)
  |> Firecracker.resource_limit("no-file", 1024)

Inspection

At any point after starting a VM, you can inspect the configuration options and status of the VM using Firecracker.describe/1 or Firecracker.describe/2. Firecracker.describe/1 will provide basic information about the state of your VM:

Firecracker.describe(vm)

This will show:

%{
  "id" => "anonymous-instance",
  "state" => "Running", 
  "app_name" => "Firecracker",
  "vmm_version" => "1.0.0"
}

Firecracker.describe/2 can be used to inspect specific configurations and metadata:

# Inspect machine configuration
machine_config = Firecracker.describe(vm, :machine_config)
# Returns CPU count, memory size, etc.

# Check balloon device configuration  
balloon_config = Firecracker.describe(vm, :balloon)
# Returns target memory size if balloon is configured

# Get balloon statistics (memory reclamation stats)
balloon_stats = Firecracker.describe(vm, :balloon_statistics)
# Returns actual memory usage, target memory, etc.

# View metadata store contents
mmds_data = Firecracker.describe(vm, :mmds)
# Returns the current metadata key-value pairs

# Get complete VM configuration
vm_config = Firecracker.describe(vm, :vm_config)
# Returns full configuration including drives, network interfaces, etc.

Snapshots

Firecracker supports creating snapshots of running VMs, which capture the complete state of the microVM including CPU registers, device states, and memory contents. Snapshots can be used for fast VM startup from saved states, creating VM templates, or implementing rollback functionality.

To create a snapshot, the VM must first be paused. Only paused VMs can be snapshotted to ensure consistent state:

# Start and boot a VM
vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker.sock")
  |> Firecracker.configure(:boot_source, kernel_image_path: kernel)
  |> Firecracker.add(:drive, "rootfs",
    path_on_host: rootfs,
    is_root_device: true,
    is_read_only: false
  )
  |> Firecracker.start()
  |> Firecracker.boot()

# Pause the VM to prepare for snapshot
paused_vm = Firecracker.pause(vm)

# Create a full snapshot
snapshot = Firecracker.snapshot(paused_vm,
  mem_file_path: "/path/to/memory.mem",
  snapshot_path: "/path/to/vm-state.json",
  type: :full
)

Firecracker supports two types of snapshots:

• :full snapshots capture the complete VM state and memory
• :diff snapshots capture only the changes since the last snapshot

To load a snapshot, you must create and start (but not boot!) a VM. Then, you can load the VM from a snapshot created with Firecracker.snapshot/2, or from a snapshot configured using the Firecracker.Snapshot module:

new_vm =
  Firecracker.new()
  |> Firecracker.set_option(:api_sock, "/tmp/firecracker-new.sock")
  |> Firecracker.start()

# Create a snapshot from file paths
snapshot = Firecracker.Snapshot.new(
  path: "/path/to/vm-state.json",
  type: :full,
  mem_file_path: "/path/to/file.mem"
)

resumed_vm = Firecracker.load(new_vm, snapshot)

When loading snapshots, you can override network interface configurations to adapt to different host environments:

snapshot =
  Firecracker.Snapshot.new(
    path: "/path/to/vm-state.json",
    type: :full,
    mem_file_path: "/path/to/memory.mem"
  )
  |> Firecracker.Snapshot.network_override("eth0", host_dev_name: "tap1")

restored_vm = Firecracker.load(new_vm, snapshot)

This is particularly useful when:

• Restoring VMs on different hosts
• The original TAP device names are no longer available
• You need to reconfigure networking after restore

Metadata

Firecracker provides a metadata service (MMDS) that allows you to inject custom data into your VMs. This metadata can be accessed from within the VM and is particularly useful for configuration management, initialization scripts, and passing runtime parameters.

You can configure metadata for your VM using the Firecracker.metadata/2 and Firecracker.metadata/3 functions. There are two ways to set metadata. Either by setting the complete metadata up front:

vm =
  Firecracker.new()
  |> Firecracker.metadata(%{
    "user_data" => "#!/bin/bash

echo 'Hello from metadata!'",

    "hostname" => "firecracker-vm",
    "environment" => "production",
    "config" => %{
      "database_url" => "postgres://localhost:5432/mydb",
      "api_key" => "abc123"
    }
  })

Or by setting/updating individual keys:

vm =
  Firecracker.new()
  |> Firecracker.metadata("user_data", "#!/bin/bash

echo 'Hello!'")

  |> Firecracker.metadata("instance_id", "i-1234567890abcdef")

Like other configuration changes, metadata modifications are data-only until applied. You need to explicitly apply them:

# Before starting the VM
vm =
  Firecracker.new()
  |> Firecracker.metadata("hostname", "web-server-1")
  |> Firecracker.start()  # Metadata is applied when starting

# After the VM is running
vm =
  vm
  |> Firecracker.metadata("status", "active")
  |> Firecracker.apply()  # Apply metadata changes to running VM

You can inspect the metadata of a VM using Firecracker.describe/2 with :mmds key:

Firecracker.describe(vm, :mmds)

I/O Rate Limiters

Firecracker provides fine-grained control over I/O operations through rate limiters that use a token bucket algorithm. These limiters help manage resource contention and ensure predictable performance when running multiple VMs.

Rate limiters control two aspects of I/O operations:

• Bandwidth - controls data transfer rate (bytes per second)
• Operations - controls frequency of I/O operations (operations per second)

You can create rate limiters with specific configurations:

# Basic rate limiter with default settings
limiter = Firecracker.RateLimiter.new()

# Rate limiter with bandwidth constraints
limiter = Firecracker.RateLimiter.new(
  bandwidth: [
    size: 10_000_000,          # 10MB bucket size
    refill_time: 100,          # Refill every 100ms
    one_time_burst: 5_000_000  # 5MB initial burst
  ]
)

# Rate limiter with operations constraints  
limiter = Firecracker.RateLimiter.new(
  ops: [
    size: 1000,                # 1000 operations max
    refill_time: 1000,         # Refill every second
    one_time_burst: 100        # 100 extra ops for burst
  ]
)

# Combined bandwidth and operations limits
limiter = Firecracker.RateLimiter.new(
  bandwidth: [size: 5_000_000, refill_time: 50],
  ops: [size: 500, refill_time: 100]
)

And apply them to any configuration that supports rate limiters:

Firecracker.configure(vm, :entropy, rate_limiter: limiter)