NanumOS

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

ButtonWhat it does
New VMOpens the window for making a new virtual machine.
StartTurns on a VM that is off.
Shut downTurns the VM off, as if you pressed its power button.
SnapshotSaves the disk as it is now.
RestorePuts the saved disk back.
Console / Hide consoleShows or hides the VM's text screen.
ScreenOpens the picture screen of a VM that has one.
Full screenFills the whole monitor with that screen.
SettingsChooses whether the console shows by itself.

Making a new VM

  1. Press "New VM".
  2. Pick a template. A template is the starting disk of the VM. Only templates in the VM store are listed.
  3. Type a name.
  4. Pick the memory: 128 MB, 256 MB, 512 MB or 2 GB.
  5. Pick the disk size: 256 MB, 512 MB or 1 GB.
  6. 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.
  7. If you want, write a "Health check" such as http:80/.
  8. 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.

KeyWhat it does
Ctrl+Shift+C, Ctrl+Shift+VCopy and paste. You can also drag to select text.
Shift+PgUp, Shift+PgDnLook 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.

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.

Showing a NanumOS folder to a VM

A running Linux VM (the Browser VM too) can be shown one folder of NanumOS, read-only.

  1. Pick the VM and click "Share a folder...".
  2. Pick the folder (a folder inside your home — not the home itself, not a hidden folder).
  3. 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

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.

CommandWhat it does
zeusos-vm start NAMEStarts the VM and waits until it answers over ssh.
zeusos-vm stop NAMESaves files and stops. It freezes the running state so the next start is fast. --cold does not freeze.
zeusos-vm listLists the VMs and their state.
zeusos-vm exec NAME COMMANDRuns one command.
zeusos-vm ssh NAMEOpens a shell in the VM.
zeusos-vm journal NAMEShows the record of what the VM did.
zeusos-vm upgrade NAME --version VSaves the workspace, then cold-boots it on another release.
zeusos-vm commit NAMECommits the shared folder to git.
zeusos-vm rm NAMEDeletes 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

What works today and what does not

Works:

Not yet:

NanumOS 0.1.8349 · 2026-11-16