NanumOS

Using NanumOS as a Mac app

NanumOS runs like any app on your Mac: a whole computer inside one window, like a picture-in-picture TV. Now: drag NanumOS.app to Applications and double-click it.

This app

How to use it

Which keys go where

KeysGo toWhy
Command-Shift-3 / 4 / 5 (also with Control)the Macthe screenshots Mac people always use; the NanumOS window is in the picture
Option-Command-Q · Command-Hthe Mac app's menuQuit (saves and shuts down) · Hide
Command-QNanumOScloses the app in front (the video player too) — pressed the Mac way, it never powers NanumOS off
Control-Command-Fthe Mac app's menuFull screen
Command-TabNanumOSNanumOS' app switcher (a Mac keyboard's Command is NanumOS' Super). To reach other Mac apps: Command-H or click another window.
Command-SpaceNanumOSa tap = NanumOS search, held = the assistant
Command-Option-EscNanumOSNanumOS' Force Quit
Control-arrows · every other keyNanumOSword moves and NanumOS' other shortcuts

Try it: click the NanumOS window and press Command-Shift-4: the Mac's crosshair appears (NanumOS gets no key). Control-Shift-4 opens NanumOS' own screenshot.

How it works

  1. Apple's built-in virtualization makes the virtual hardware; the chip runs NanumOS directly.
  2. Dropped files are pushed in by the Mac app. NanumOS only receives — it cannot reach the Mac's files or apps, like a courier leaving a parcel at the door: from inside the house you cannot open the warehouse outside.
  3. A file with a name already there is never overwritten; it becomes "name 2".
  4. When the assistant reads a page, the Mac app decides too. NanumOS can only send one line, "read the page now"; the app checks the switches and hands over the title, address and text (up to 16 KB) — no cookies, no form values, no other tabs. Like a counter clerk handing over one photocopy, not the file cabinet.
  5. Your files are saved in two alternating copies. Growing the disk moves the second copy's place, so the app first copies that second copy to its new place: whichever copy is newer opens as before.
  6. The Assistant's ears and mouth are the Mac app's too. NanumOS only sends lines such as "listen", "read this sentence", "stop"; the Mac turns what it heard into text by itself (no internet) and sends the text back, so the sound never leaves the Mac.

Try it: drop a photo on the window, then open Files › Downloads in NanumOS. With the Mac's browser on, ask the assistant "sum up the page open in the Mac web window" and watch the orange line on the web window.

Technical details

Apple Virtualization.framework (VZ): virtio-gpu screen (window size → display event → re-layout), USB keyboard and pointer, virtio-net NAT, virtio-blk home disk, virtio-sound, the SPICE agent clipboard, and a named virtio-console port kim.zeus.drop (Mac → NanumOS files and commands, NanumOS → Mac one-line answers). On M3 or newer with macOS 15+, nested virtualization (EL2) is on and a second disk vmstore.raw (ZEUSOS-VMSTORE-v1, 16 GiB sparse) is attached. The home disk home.raw is a 4 GiB sparse lab disk (two save banks of (sectors − 16384) / 2 each). Assistant reads: the guest's read → the app's page <bytes> + "title\nurl\ntext" (WKWebView innerText), a refusal is page 0; appdo browser.host_browser_open / host_browser_read (needs_ok 0). Operating: the guest only asks with the lines hgrant <origin> <task>, hlist, hclick N, hconfirm N, htype N text, hfind text and hdone; the Mac app answers hres ok|no .... The text of the approval cards (host_browser_allow, host_browser_confirm_click, needs_ok 1) is built by code from the origin (scheme, host, port) of the page the app sent, and the app refuses an hgrant whose origin is not the origin of the page open now. A grant is bound to one origin and ends when the site changes, when the person's own mouse, key or scroll hits the web view, at the stop switch, at hdone, or after 10 minutes without an action. Password, card, one-time-code and file fields are never filled; a submit button (a POST form, or any form with a password or card field) is recognised by the code from the element's attributes and asks every time. The log data/hostweb-actions.log keeps verbs, kinds and results only, never typed or page text. The app's saved machine state (keepstate) is still opt-in — after a restore the named ports and the network stay silent. Developer notes: docs/MAC-APP.md. Voice: guest vlisten 1 auto|hold|duplex ko|en · vlisten 0 · vsay <sentence> · vstop · vvoice <voice name>|mac → app vheard partial|end|final <ms> <text> · vsaid start <ms> <voice>|end|stop, availability cmd hostvoice 1|0; SFSpeechRecognizer (requiresOnDeviceRecognition, ko-KR / en-US) hears; reading is the app's Contents/MacOS/nanum-speak (user/speak built for macOS, --serve: a sentence line in, 24 kHz pieces out) + Resources/voices (the Minseo pack) — the pieces go straight into the microphone's echo-cancelling engine, so barge-in works as before. AVSpeechSynthesizer only for English sentences, vvoice mac, or an app without the voice pack. The full list: docs/contracts/VOICE.md "Host voice". Keys: the view (VZVirtualMachineView) captures system keys (capturesSystemKeys) so Command-Tab and Command-Space reach NanumOS. While Command and Shift are held without Option the capture is off, so macOS' screenshot keys go to the Mac. A Command-Shift-3/4/5/6 that still reaches the view is never given to NanumOS; the app takes the same capture with macOS' screencapture. Test: tests/mac_app.py 12 (NanumOS' opt/zeusos/keytrace=on log shows which keys arrived).

NanumOS 0.1.8349 · 2026-11-16