Skip to main content

Virtualbox

Guide: Setting up VirtualBox on macOS with a Custom NixOS Image​

This guide outlines the process for installing and configuring VirtualBox on macOS and setting up a custom NixOS image that includes an automated install script (matrix-install).

Part 1: Installing VirtualBox on macOS​

Prerequisites​

  • macOS 12 or later (Intel or Apple Silicon with x86_64 virtualization support)
  • Administrator access

Step-by-Step Installation​

  1. Download VirtualBox

  2. Install VirtualBox

    • Open the .dmg file and run the installer.
    • You may need to allow the extension in System Preferences > Security & Privacy if blocked.
    • Reboot your system if prompted.

  3. (Optional) Install VirtualBox Extension Pack

    • Download and install the matching version of the Extension Pack from the same downloads page.
    • Double-click the .vbox-extpack file to add it to VirtualBox.

  4. Verify Installation

    • Run VirtualBox from /Applications.
    • Confirm version and ensure the UI loads correctly.

Part 2: Acquiring the Custom NixOS Image​

Instead of building the image on each host system (which is not feasible on macOS or Windows), the recommended method is to build the custom installation ISO on a Linux machine with Nix installed, then publish it as a release artifact.

Pre-built ISO Download​

  1. Access the Release Page

    • Navigate to the GitHub repository hosting the custom NixOS flake.
    • Go to the Releases section and download the latest ISO image (e.g., nixos-minimal-25.05.20250429.46e634b-x86_64-linux.iso).

  2. Verify Integrity

    • Validate the checksum (e.g., shasum -a 256 nixos-minimal-25.05.20250429.46e634b-x86_64-linux.iso) to ensure the download was not corrupted.

  3. Store ISO Locally

    • Place the downloaded ISO file in an accessible location for use in VirtualBox.

Part 3: Setting Up a NixOS VM with matrix-install​

Prerequisites​

  • VirtualBox installed
  • A NixOS ISO image that includes the matrix-install script
  • PAT (GitHub Personal Access Token) and flake profile identifier

Step-by-Step Configuration​

  1. Create a New Virtual Machine

    • Open VirtualBox and click New.
    • Name: e.g., NixOS-VM
    • Type: Linux
    • Version: Other Linux (64-bit)

  2. Configure VM Settings

    • Memory: Allocate at least 2048 MB (4096 MB recommended).
    • Hard Disk: Create a new VDI image (dynamically allocated, 20GB+).
    • Processor: Allocate 2 or more CPUs if available.

  3. Attach ISO Image

    • Go to Settings > Storage.
    • Under Controller: IDE, click the empty disk.
    • Click the disk icon > Choose a disk file.
    • Select the custom NixOS ISO with matrix-install.

  4. Start the VM and Enter Live Environment

    • Boot the VM and select the appropriate boot option.
    • Gain root access: sudo -i

  5. Run matrix-install Script

# Usage:
# matrix-install <PAT> <profile> <disk> <username> <description>

# Example
matrix-install ghp_ABC123456789xyz matrix-virtualbox /dev/sda alice "Dev Workstation"

Script Behavior Summary​

  • Pre-checks: Ensures root and five arguments are supplied.

  • Disk Wipe: Prompts and securely wipes the target disk using wipefs.

  • Partitioning: Uses sgdisk to create:

    • EFI (1GB)
    • Swap (~50% of RAM)
    • ZFS root

  • ZFS Setup:

    • AES-256-GCM encrypted ZFS pool with compression and optimized defaults.
    • Mounts pool to /mnt, sets up /mnt/tmp and /mnt/boot.

  • Boot Partition: Formats EFI partition as FAT32.

  • Nix Registry: Registers the custom flake source matrixai/nixpkgs-matrix-private.

  • Installation: Performs a nixos-install with the given flake profile and GitHub PAT.

  • User Setup:

    • Creates user with appropriate groups
    • Prompts for user password
    • Locks the root account

  • Final Step: Reboots the VM.

Post-Installation Steps​

  1. Initial Login

    • Log in as the user created during matrix-install.

  2. Check ZFS

    • Validate that the ZFS pool is correctly mounted.
    • Run zpool status and df -h.

  3. Networking and SSH

    • Ensure networking is functional.
    • If needed, configure port forwarding for SSH via VirtualBox networking settings.

  4. Snapshotting (Optional)

    • After setup, take a snapshot via VirtualBox for future rollbacks.

Troubleshooting Tips​

  • Missing EFI boot option: Check that the EFI partition is correctly formatted and mounted.
  • Swap or ZFS errors: Confirm partitions exist (lsblk), and verify correct device naming inside the VM.
  • GitHub flake access issues: Double-check the PAT and repo permissions.

Conclusion​

This setup allows for reproducible, encrypted, and customizable NixOS installations within VirtualBox on macOS, Windows, or Linux. By distributing a pre-built ISO, the need for local Nix installations is removed, broadening platform compatibility. The matrix-install script automates and enforces consistent system state, especially useful in infrastructure-as-code workflows.