# 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.

*Diagram: 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](https://github.com/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.](https://muxin.dev/images/shots/vmnew-dark.png?v=635d9c3f)

*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.

> **Tip:** 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](https://muxin.dev/docs/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.](https://muxin.dev/images/shots/vm-dark.png?v=71df5bf7)

*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.

> **Warning:** Destroy can’t be undone. Muxen asks first.

## From your agents and the command line

Your AI agents can do the same through [MCP](https://muxin.dev/docs/agents): `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.