fbx-vm

Declarative NixOS virtual machines for Freebox Delta.

Overview

fbx-vm enables you to build and deploy declarative NixOS virtual machines on your Freebox Delta using Nix flakes. Build VM images from any system (cross-compilation supported), and deploy reproducible VMs to your Freebox.

Quick Start

# Build the VM image
nix build .#fbx-vm

# Test locally with QEMU
nix run .#test-fbx-vm result/nixos.qcow2

# SSH into test VM
ssh -p 2222 root@localhost  # password: changeme

Use in Your Own Flake

Import the flake-parts module to build your own customized Freebox VM:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
    flake-parts.url = "github:hercules-ci/flake-parts";
    fbx-vm.url = "github:firefly-engineering/fbx-vm";
  };

  outputs = inputs @ { flake-parts, ... }:
    flake-parts.lib.mkFlake { inherit inputs; } {
      imports = [ inputs.fbx-vm.flakeModules.freebox ];

      systems = [ "x86_64-linux" "aarch64-linux" ];

      freebox.vm = {
        enable = true;
        modules = [
          # Your VM configuration
          ({ pkgs, ... }: {
            networking.hostName = "my-freebox-vm";
            users.users.root.initialPassword = "changeme";
            services.openssh.enable = true;
            environment.systemPackages = [ pkgs.htop ];
          })
        ];
      };
    };
}

This gives you:

• packages.<system>.fbx-vm - QCOW2 disk image
• packages.<system>.test-fbx-vm - QEMU test script
• nixosConfigurations.freebox-vm - NixOS configuration

The base configuration automatically includes:

• Freebox hardware support (VirtIO, serial console)
• Minimal kernel with debug info disabled
• system.stateVersion = "25.11"

Requirements

• Target: ARM64 (aarch64-linux) - Freebox Delta VMs are ARM64 only
• Image format: QCOW2 with GPT/EFI partition table
• Boot: UEFI only (no legacy BIOS)

Build System Setup

On x86_64-linux (cross-compilation):

# /etc/nixos/configuration.nix
boot.binfmt.emulatedSystems = [ "aarch64-linux" ];

On aarch64-linux: Native compilation, no extra setup needed.

On macOS: Requires a Linux builder (nixbuild.net, remote builder, or VM).

Project Structure

fbx-vm/
├── flake.nix                 # Main flake (uses flake-parts)
├── flake-parts/
│   └── freebox.nix           # Reusable flake-parts module
├── modules/freebox/          # NixOS hardware module
│   ├── default.nix
│   ├── hardware.nix          # VirtIO, serial console config
│   └── minimal-kernel.nix    # Kernel optimization
└── images/minimal/           # Example minimal configuration
    └── configuration.nix

Exports

Output	Description
flakeModules.freebox	Flake-parts module for downstream flakes
nixosModules.freebox	NixOS module (hardware config only)
packages.<system>.fbx-vm	QCOW2 disk image
packages.<system>.test-fbx-vm	QEMU test script

Deployment

1. Build: nix build .#fbx-vm
2. Copy result/nixos.qcow2 to your Freebox via the web interface or API
3. Create a VM in Freebox OS using the uploaded image
4. Boot and SSH in

License

MIT