Virtual Machines
How to start and stop small computers (virtual machines, VMs) inside NanumOS. This page covers the Virtual Machines app on the desktop and the zeusos-vm command for a development computer.
What a virtual machine is
A virtual machine is another computer running inside your computer. It has its own memory, its own disk and its own screen. If something goes wrong, it goes wrong inside the VM only. Delete the VM and nothing is left behind.
NanumOS uses the CPU's virtualization feature directly (VT-x / VMX on Intel PCs, ARM EL2 in the Mac window). On a computer without it, the app says "Virtual machines need the hypervisor of NanumOS on this computer."
The Virtual Machines app
Open "Virtual Machines" from the dock or the app list. The VM list is on the left and the selected VM is on the right. On a phone screen the list is on top and the VM is below.
A VM shows as "Running", "Stopping" or "Off". A VM with a health check also shows "checking", "healthy", "failing" or "gave up".
| Button | What it does |
|---|---|
| New VM | Opens the window for making a new virtual machine. |
| Start | Turns on a VM that is off. |
| Shut down | Turns the VM off, as if you pressed its power button. |
| Snapshot | Saves the disk as it is now. |
| Restore | Puts the saved disk back. |
| Console / Hide console | Shows or hides the VM's text screen. |
| Screen | Opens the picture screen of a VM that has one. |
| Full screen | Fills the whole monitor with that screen. |
| Settings | Chooses whether the console shows by itself. |
Making a new VM
- Press "New VM".
- Pick a template. A template is the starting disk of the VM. Only templates in the VM store are listed.
- Type a name.
- Pick the memory: 128 MB, 256 MB, 512 MB or 2 GB.
- Pick the disk size: 256 MB, 512 MB or 1 GB.
- If you want, write a "Port forward" such as
8080:80. Connections to port 8080 on this computer go to port 80 in the VM. - If you want, write a "Health check" such as
http:80/. - Press "Create".
The app copies the template's disk, checks it, starts the VM and opens its console. The login screen usually shows up within a few seconds to about ten. If there is no template at all, you see "No template in the VM store".
The console
The console is the same text screen as the Terminal app. It has colors, cursor movement, scrollback, and full-screen programs such as top and vi. Click the console once and every key goes to the VM. You can type Korean too.
| Key | What it does |
|---|---|
Ctrl+Shift+C, Ctrl+Shift+V | Copy and paste. You can also drag to select text. |
Shift+PgUp, Shift+PgDn | Look at earlier output. |
While the console has the keyboard, Ctrl+W does not close the window. Click outside the console to take the keyboard back, then close.
The Chromium VM that serves as the browser
The "Chromium" app shows a real Chromium running in a small Linux VM, inside its window. The VM made from the chromium template does this work. It uses 2 GB of memory by default.
- You can also open the VM's screen with "Screen" in the Virtual Machines app.
- This VM's disk returns to its first state when you turn it off and on. Bookmarks and logins do not stay.
- See Browser (Chromium VM, Lab) for how to use it.
Full screen and its shortcut
Press Ctrl+Alt+Enter and the screen of a Chromium VM or a NanumOS guest fills the whole monitor. Every key goes to the VM then. Move the mouse to the top edge and click the bar that appears, or press Ctrl+Alt+Enter again, to return to the desktop. Shift with Space still switches between Korean and Latin typing.
NanumOS inside NanumOS
A VM made from the zeusos template starts a copy of NanumOS as a guest. The guest has its own screen and its own disk.
- Look at the guest with "Screen" or "Full screen". The keyboard works.
- The disk is saved before every start, so you can change anything and press "Restore" to return to how the session began.
- Files saved inside the guest stay on its disk and are there in the next session.
Showing a NanumOS folder to a VM
A running Linux VM (the Browser VM too) can be shown one folder of NanumOS, read-only.
- Pick the VM and click "Share a folder...".
- Pick the folder (a folder inside your home — not the home itself, not a hidden folder).
- The VM's row then says "Sharing Documents › Contracts (read-only)"; "Stop sharing" ends it at once.
How it works: think of a glass cabinet. The VM can look in but cannot reach in. Each time the VM reads a file NanumOS checks it against the share as it is at that moment, so stopping it also stops files the VM already has open. Closing the VM's window or shutting the VM down stops it by itself. Hidden files (names starting with .) are not shown and nothing outside the folder can be reached. What was opened is written to /var/log/vmx.log as names and sizes only (never contents).
Technical details
A virtio-fs device (tag zeus, x86 PCI 00:04.0, arm64 virtio-mmio slot 5). NanumOS (src/vshare.c) answers every FUSE request: every write is EROFS, .., paths and hidden names are refused, invented node numbers are checked against the folder again, files are direct I/O with 0 s entry caching. Terminal: vmx share NAME FOLDER [for=SECONDS] · vmx share NAME off · vmx share NAME (status). Design: docs/HV-SHARING.md.
Receiving a file from a VM
Terminal: vmx share NAME offers · vmx share NAME accept N · vmx share NAME decline N.
Sharing one folder
When you start a VM with zeusos-vm on a development computer, add --share to let the VM read and write one folder of your computer.
zeusos-vm start NAME --share FOLDER
- Your home folder,
/, and any folder above your home are refused. - A symbolic link is refused.
- A folder that is not empty must be a git repository, or it is refused. Add
--forceif you really mean it. - The VM's record of what it did (the journal) is kept where the VM cannot erase it.
- At start, the screen tells you loudly which folder is shared.
zeusos-vm on a development computer
zeusos-vm starts several NanumOS VMs with QEMU on a Mac or Linux computer. They run without a screen and each has its own workspace.
| Command | What it does |
|---|---|
zeusos-vm start NAME | Starts the VM and waits until it answers over ssh. |
zeusos-vm stop NAME | Saves files and stops. It freezes the running state so the next start is fast. --cold does not freeze. |
zeusos-vm list | Lists the VMs and their state. |
zeusos-vm exec NAME COMMAND | Runs one command. |
zeusos-vm ssh NAME | Opens a shell in the VM. |
zeusos-vm journal NAME | Shows the record of what the VM did. |
zeusos-vm upgrade NAME --version V | Saves the workspace, then cold-boots it on another release. |
zeusos-vm commit NAME | Commits the shared folder to git. |
zeusos-vm rm NAME | Deletes the VM and its workspace. |
A VM starts from a signed, verified stable release. If the check fails, it does not start. The workspace disk is 64 MiB.
Copy and paste with a VM
Text copied in NanumOS pastes in a running VM, and text copied in a VM pastes in NanumOS (Korean as is, up to 64 KiB). In a Mac or PC window it chains one step at a time: Mac ↔ NanumOS ↔ VM ↔ the VM inside it. A Linux VM needs spice-vdagent (an Ubuntu or Alpine package); a NanumOS guest works as it is. The text moves when you paste, and Vault passwords never go to a VM. Select a VM in the Virtual Machines app to find its "Share clipboard" switch (on by default; the same as vmx clip NAME off).
Network
- Private cable: a virtual cable that joins two NanumOS machines on the same computer to each other only.
- slirp (user network): the VM can reach the internet, but nothing from outside can reach the VM.
zeusos-vmuses this and connects one local address of the computer to the VM's ssh. - A connection straight onto the computer's real network (a bridge) is not used yet.
What works today and what does not
Works:
- In the Virtual Machines app: making, starting, stopping, snapshotting and restoring Linux VMs, and the console.
- Port forward and health check.
- The Chromium VM, its screen and full screen.
- Starting a NanumOS guest, its screen, its keyboard and restore.
zeusos-vmon a development computer.- Copy and paste of text with VMs (Linux with
spice-vdagent, a NanumOS guest as it is). - Showing one NanumOS folder, read-only, to a running Linux VM ("Share a folder...").
Not yet:
- Each VM has one CPU. More CPUs are coming soon.
- A NanumOS guest has no mouse and no network. Coming soon.
- Changing a guest's screen size after it started does not work.
- Up to four VMs can run at once. The app list shows up to eight.
- Giving a graphics card (GPU) straight to a VM does not work.
- This manual has no result yet from running VMs on a real laptop. Most tests ran in virtualization inside virtualization.
NanumOS 0.1.8349 · 2026-11-16