Skip to content
Muxen
Docs · VMs on your machines

Your machines

VMs on your machines

Make a Windows or Linux VM on a machine you already have, use it like any other machine, and destroy it when you’re done.

Need a clean Windows to try an installer, or a throwaway Linux for an agent to work in? New VM makes one on a machine you already have, sets it up with your ssh key, and adds it to your machines, under the one it runs on. From then on it’s a machine like the others: sessions, files, servers, workspaces and its desktop all work.

This computer

ssh goes through Beacon (-J) to the port each VM publishes; a UDP port is forwarded for direct connections.

Beacon

Ubuntu, with Docker and KVM

win-test

Windows 11 · VM

muxen-win-test muxen-agent

ubuntu-1

Ubuntu 24.04 · Container

muxen-ubuntu-1 muxen-agent
Each VM is a Docker container on a machine you already have, and one of your machines in Muxen, shown under it.

What you can run, and where

  • Windows: Windows 11, Windows 10, Windows Server 2025 or Windows Server 2022. It runs in Docker with KVM (dockur/windows), so its host must be a Linux machine (x86-64) with Docker and /dev/kvm, like a mini PC or a server, with about 30 GB free.
  • Linux: Ubuntu 26.04, Ubuntu 24.04, Debian 13, Fedora, Alpine or Arch Linux (Arch on x86-64 only). It’s a container with ssh, on any machine with Docker, this Mac included. It’s ready in under a minute and shares its host’s kernel, so there’s no systemd inside.

A VM can’t run inside another VM. If none of your machines can run what you picked, the dialog says what it needs.

Making one

Open New VM from any of these:

  • New VM… in the Add machine dialog (⌘N).
  • New VM… in the command palette (⌘⇧P).
  • New VM here… in a machine’s right-click menu, on machines that can run one.
  • The New VM choice in the New session dialog (⌘T): it makes an Ubuntu VM and starts the session in it, for an agent you want to keep off your real machines.

Pick a name, a system, the machine it runs on (with its free memory), and a size: 2, 4 or 8 CPUs, 4, 8 or 16 GB of memory, and for Windows a 64, 128 or 256 GB disk. The defaults are 4 CPUs, 8 GB and 64 GB.

The New VM dialog: a name, the system (Windows 11 picked), the machine it runs on (Beacon), and its CPUs, memory and disk. The New VM dialog: a name, the system (Windows 11 picked), the machine it runs on (Beacon), and its CPUs, memory and disk.
Windows 11 on Beacon: the dialog says how long it takes, and what the host needs.

What a Linux VM comes with

Under Comes with, pick the agent CLIs to install: Claude Code (on by default), Codex, Gemini CLI and OpenCode. They’re installed with Node.js as the VM starts, which adds a few minutes, and sign in the first time you use them. On Ubuntu, Debian and Fedora the GitHub CLI comes too.

The Windows install

Windows downloads itself (about 6 GB) and installs on its own: 15 to 30 minutes the first time. Then a first-boot script turns on OpenSSH with your key, and Muxen installs its agent.

  • It joins your machines as soon as its container starts, and shows as Installing… in the sidebar until Windows answers ssh.
  • Watch the install on its page shows its screen in your browser, at localhost.
  • It runs unactivated until you enter a key.
  • Muxen makes its Windows account’s password and keeps it in your Keychain. Copy password on its page copies it, for signing in on its screen.

The dialog closes as soon as the VM starts being made, so you can carry on. Its progress, Docker’s output included, is in Activity (⌘J).

Using it

A VM’s page starts with a card that says where it runs (“Virtual machine on Beacon”, or “Container on Forge”) and whether its container is running, with:

  • Stop and Start. Stop gives Windows two minutes to shut down cleanly; Start waits until it answers ssh. Both are in its right-click menu too.
  • Copy password (Windows) and Open Beacon, its host.
  • Destroy…

Its host forwards a UDP port to each VM, so Connect directly works on a VM like on any machine. See Connections.

win-test's page: a Virtual machine on Beacon card with Stop, Copy password, Open Beacon and Destroy, and the sidebar with win-test under Beacon. win-test's page: a Virtual machine on Beacon card with Stop, Copy password, Open Beacon and Destroy, and the sidebar with win-test under Beacon.
A Windows VM on Beacon, and in the sidebar under it.

When a VM can’t be reached, it says why: “win-test is stopped” (start it), or “Beacon is offline” when its host is off.

Destroying it

Destroy… deletes its container and its disk on the host (under ~/.muxen/vms/), and takes it out of Muxen. Everything in it is gone, so copy out anything worth keeping first. To keep a VM without it using memory, Stop it instead.

Destroy can’t be undone. Muxen asks first.

From your agents and the command line

Your AI agents can do the same through MCP: vm_options says where VMs can run and what, vm_create makes one (for Windows, with wait: false, then poll the operation), machine_power starts and stops one, and vm_destroy deletes it. Make a Windows VM for a test, use it, destroy it.

muxen vm options                                    # where VMs can run, and what
muxen vm create win-test --system windows-11 --on beacon
muxen vm create scratch --system ubuntu-24.04 --install claude,codex
muxen power win-test off
muxen vm destroy win-test

Without --on, it goes on the machine with the most free memory that can run it. --cpus, --memory and --disk (in GB) set its size.