|
| 1 | +# Experimental Devbox VM |
| 2 | + |
| 3 | +Experimental support for Devbox virtual machines on macOS. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +The `dxvm` command acts like `devbox shell` except that it launches the Devbox |
| 8 | +environment in a VM. |
| 9 | + |
| 10 | +To create a new VM, run the following: |
| 11 | + |
| 12 | + cd ~/my/project |
| 13 | + dxvm -install |
| 14 | + # Wait for the prompt. This might appear to hang the first time it's run |
| 15 | + # while downloading the NixOS installer. |
| 16 | + |
| 17 | + mkdir bootstrap |
| 18 | + sudo mount -t virtiofs bootstrap bootstrap |
| 19 | + sudo bootstrap/install.sh |
| 20 | + sudo shutdown now |
| 21 | + # ^C to exit |
| 22 | + |
| 23 | +Now that the VM is bootstrapped, you can launch it any time with: |
| 24 | + |
| 25 | + cd ~/my/project |
| 26 | + dxvm |
| 27 | + |
| 28 | +The NixOS installer files are cached in `~/.local/state/devbox/vm`. You can |
| 29 | +monitor the ISO in this directory to estimate how far along the download is. The |
| 30 | +final size should be around 800 MiB. |
| 31 | + |
| 32 | +The first time `dxvm` is run in a Devbox project, it creates a `.devbox/vm` |
| 33 | +directory that contains the VM's state and configuration files: |
| 34 | + |
| 35 | +- `log` - error and debug log messages |
| 36 | +- `disk.img` - main disk image, typically mounted as root |
| 37 | +- `id` - an opaque Virtualization Framework machine ID |
| 38 | + |
| 39 | +The following files can be edited (for example, `echo 4 > cpu`) to adjust the |
| 40 | +VM's resources: |
| 41 | + |
| 42 | +- `mem` - the amount of memory (in bytes) to allocate to the VM |
| 43 | +- `cpu` - the number of CPUs to allocate to the VM |
| 44 | + |
| 45 | +## Building |
| 46 | + |
| 47 | +This package uses the macOS Virtualization Framework, and therefore needs CGO. |
| 48 | +Devbox and Nix are unable to download the macOS SDK directly, so some extra |
| 49 | +setup is required: |
| 50 | + |
| 51 | +- macOS Ventura (13) or later |
| 52 | +- XCode command line tools (open Xcode at least once to accept the EULA) |
| 53 | + |
| 54 | +To compile and sign `dxvm` run: |
| 55 | + |
| 56 | + devbox run build |
| 57 | + |
| 58 | +The `devbox run build` script uses `./cmd/dxvmsign` to sign the Go binary, which |
| 59 | +allows it to use the Virtualization Framework. It's a small wrapper around |
| 60 | +Apple's `codesign` utility. |
| 61 | + |
| 62 | +## Limitations |
| 63 | + |
| 64 | +- Mounting the Devbox project directory was temporarily removed while cleaning |
| 65 | +things up. Needs to be brought back. |
| 66 | +- Only aarch64-linux is implemented right now. Other systems have been tested, |
| 67 | +but they aren't an option in the dxvm command. |
| 68 | +- Using ctrl-c to exit has the unfortunate side-effect of making it impossible |
| 69 | +to interrupt a program in the VM. |
| 70 | +- The host terminal has no way of telling the guest when it has resized (usually |
| 71 | +this is done with SIGWINCH). Running less/vim/etc. in the VM might look messed |
| 72 | +up. Run `stty cols X rows Y` in the VM to manually set the size of your terminal |
| 73 | +window. |
| 74 | + |
| 75 | +# Todo/Ideas |
| 76 | + |
| 77 | +- Support macOS and x86_64-linux. |
| 78 | +- macOS Sonoma added support for VM suspend/resume. This would probably make VM |
| 79 | +start times a lot faster (maybe instant?). |
| 80 | +- Clipboard sharing. |
| 81 | +- Expose sockets for services. |
| 82 | +- Mount /nix/store as an overlay to share packages between VMs. |
| 83 | +- Communicate directly with the host Nix daemon? |
| 84 | +- Disk resizing. |
| 85 | +- Memory balloon (adjust VM memory at runtime). |
| 86 | +- Multiple consoles. |
| 87 | + |
| 88 | +## Docs |
| 89 | + |
| 90 | +Some useful links for learning more about the Virtualization Framework: |
| 91 | + |
| 92 | +- `vz` - Go bindings for Apple's Virtualization Framework |
| 93 | + - <https://github.com/Code-Hex/vz> |
| 94 | + - <https://github.com/Code-Hex/vz/wiki> |
| 95 | + - <https://pkg.go.dev/github.com/Code-Hex/vz/v3> |
| 96 | +- Virtualization Framework |
| 97 | + - <https://developer.apple.com/documentation/virtualization> |
0 commit comments