box
Make a Linux machine. Get a shell in it.
box turns a distro's own WSL image into a running machine with one command — a user you can log in as, sudo that just works, and a shell waiting. Seven verbs, on Windows, with nothing to install but WSL itself.
Windows · PowerShell
irm https://box.optersoft.com/install.ps1 | iexbox 0.4.0 for Windows x86-64. Download box.exe directly, or read the checksum the installer verifies it against.
What you need
WSL, and nothing else. box drives it; it does not replace it.
WSL
Windows ships it. box imports a distro's own root filesystem into it, seeds it and hands you a shell with a user already on it — no virtual machine to configure, no second kernel, nothing else installed.
wsl --install --no-distributionusbipd, only for USB
box usb is the one command with a dependency of its own: usbipd-win is what actually hands a device across. Every other command needs nothing but WSL.
winget install usbipdThe installer above puts box.exe in %LOCALAPPDATA%\Programs\box and adds it to your PATH. Run it again to update — it overwrites the binary in place.
What a machine comes with
The same four things every time, so you can script against them.
A user you can sudo as
box, at uid 1000, with passwordless sudo — the same user whichever kind of machine it is.
A shell, one command away
box ssh alfa starts it if it is stopped and puts you in it. The machine is local, so there is nothing to wait for.
A name that is the hostname
box sets it when the machine is created, in /etc/wsl.conf and /etc/hostname, so the shell prompt says which machine you are in.
No wsl --import arguments
wsl --import leaves you a machine with no user at all. box does the setup the distro's own installer would have done, and the arguments wsl.exe does not make obvious are the point of the tool.
The commands
All of them. create, start, stop and delete take any number of names.
| Command | What it does |
|---|---|
box create alfa | A new Ubuntu machine named alfa. |
box ssh alfa | Start it if needed, open a shell as box. |
box list | Every machine box made, with its state and address. |
box start alfa | Boot it. |
box stop alfa | Terminate it. |
box compact alfa | Shrink its disk back to what is used inside. |
box delete alfa | Unregister it and delete the disk. |
box images | What each image resolves to today, and whether it is cached. |
box forward add alfa 8080 | Publish a port to the rest of the network. |
box export alfa a.tar | Back it up — and restore, clone, move, sparse. |
And then the rest of it
create, start, stop, delete, list, ssh and ip are the seven you type. The other twenty sit beside them, not under a subcommand — there is one kind of machine, so there is one list.
Move it around
export, restore, clone and move — a machine is a file you can hand to somebody, and clone gives thirty students the same starting point.
Reach it
forward add publishes a port to the rest of the network, firewall rule included. forward repair re-points every rule after a restart, which is when they break.
Attach things
mount takes a physical disk or a .vhdx; usb attach hands over a USB device through usbipd.
Tune the lot
vm is the .wslconfig every machine on the computer shares — memory, processors, networking.
Images resolve themselves
box reads the same index wsl --list --online does, and checks the download against the SHA-256 published beside it. A new release is a new download, never a new version of box.
| --image | What it resolves to | Releases |
|---|---|---|
ubuntu | The newest Ubuntu WSL image. ubuntu:24.04 pins a release. | 20.04 - 26.04 |
debian | Debian stable, and the smallest of the four at 85 MB. | 13 (trixie) |
fedora | The newest Fedora WSL image. fedora:43 pins one. | 43, 44 |
alma | AlmaLinux, for RHEL-compatible work. almalinux works too. | 8, 9, 10 |
Offline, box uses the last index it saw; on a first run with no network at all, a pinned build it ships with. Either way the download is verified before it is cached.
There is a window, too
box-gui is the same thing with a list in it: every machine, its state and its address, a create form, and the narration of whatever is running. Anything it does, box does — they are two front ends over one library.
It is not in the download above yet, and that is now a choice rather than a limit: the Windows build here is cross-compiled from macOS, and the GUI's renderer can be cross-compiled with it. For the moment box.exe is the command line, and it is the whole tool.
Where things live
| What | Where |
|---|---|
| Machines — the disk WSL keeps them in | %APPDATA%\box\wsl\<name>\ |
| Downloaded root filesystems | %APPDATA%\box\cache\ |
| Your SSH key | ~\.ssh\id_ed25519 |
box delete removes a machine's folder. Your key and the image cache are left alone — and box list only ever shows machines box made.
box is proprietary software. It is free to download and use; the source is not public. This build is 0.4.0.