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
- Resize the window and NanumOS' screen follows. Full screen: Control-Command-F.
- Drag files from Finder onto the window: they are copied into Downloads in NanumOS (also Machine › Send Files to NanumOS).
- Bring in from the Mac: drag a file from the Mac desktop onto an app that takes files (Video Retouch, Photo Retouch, Files) and that app opens it; drop it anywhere else and it goes to Downloads with a notice. In an app's Import… sheet, press "Import from this Mac…": the Mac's file panel opens (showing only what that app handles), only the files you choose are copied, and the app opens them. NanumOS never looks into or mounts a Mac folder by itself; only what you pick or drag goes. Photos dragged from the Photos app, attachments from Mail and images from Safari come in too (those apps hand over a "file promise" instead of a file: the app makes the file at the moment you let go); a folder comes whole, sub folders too; many files come at once.
- Send to the Mac: in Files, choose a file or folder and press File › "Send to Mac…" (Shift+Ctrl+E): the Mac's save panel opens and you choose where and under which name (a folder, for several). An app's Save As sheet (Notepad and the others) has "Save to Mac…": it saves in NanumOS and then hands the same file to the Mac's save panel; Photo Retouch's Export As and Video Retouch's finished-export line have "Save to Mac…" too.
- Drag out: drag an item from Files or the desktop out of the window onto the Mac desktop or a Finder window: it is copied there. NanumOS sends the file only when the Mac says it was let go there; the original stays in NanumOS.
- Copy and paste text both ways between the Mac and NanumOS. Sound plays through the Mac.
- Menu NanumOS › Quit NanumOS (Option-Command-Q) or Machine › Shut Down: NanumOS saves your files and shuts down cleanly. The red button closes the NanumOS app in front (the video player too); on the bare desktop it only hides the window — NanumOS keeps running, sound and radio too; the Dock icon or Window › NanumOS (Command-0) brings it back as it was. Command-Q is NanumOS' own (it closes the app in front).
- Where keys go: with the window in front, NanumOS gets the keys. Only the Mac's screenshots (Command-Shift-3 whole screen · Command-Shift-4 a part · Command-Shift-5 the capture bar, with Control to the clipboard) always go to the Mac — like a doorbell: even in your room, the house hears it. Screenshots inside NanumOS are Control-Shift-3/4/5 and Command-Shift-S.
How to use it
- Menu Machine: Start · Shut Down · Restart · Send Files to NanumOS · Import vault (sends only your encrypted .kdbx; see the Vault chapter) · Memory and Processors (used at the next start) · Use the Mac's Browser · The Assistant in the Mac's Browser · Devices for NanumOS · Hear and Read on the Mac.
- Your files have 4 GB of room. The Mac's disk holds only what is really written (empty room takes no space). A 64 MB home from an earlier version grows by itself at the next start with every file kept (the old one stays once as "home-64MiB-before-grow.raw").
- One dropped file may be up to 256 MB; a bigger one is not sent and the line under the title says so. NanumOS names are up to 31 bytes (about 10 Korean letters): a longer name is shortened, and you are told.
- On an M3 or newer Mac there is also room for virtual machines inside NanumOS (16 GB, again only what is used). The browser VM template is not included yet, so meanwhile the Browser opens Z브라우저 and says why once.
- Your NanumOS files are in one place on the Mac (Application Support › NanumOS). Menu NanumOS › Show My Files.
- Use the Mac's Browser (optional, off by default): NanumOS' Browser then opens on top of NanumOS. Its title bar, moving, resizing and closing work like any NanumOS window; the page itself is shown by the Mac app over the window's body. While the page has focus, Cmd-Tab and Cmd-Space go to macOS; click the NanumOS title bar to get them back. Pages, history and logins stay on this Mac, not inside NanumOS.
- The assistant in the Mac's browser: with that option on, the assistant may open a page in the web window and read the open page's title, address and text (no approval card — looking and reading can be undone). While it reads, an orange line "The assistant is reading this page" shows on the web window. To click or type it needs your OK on a card "<site>: allow operating the page for <task>?", and then only on that site for that task (it ends at once when the site changes or you touch the web window; a red line "The assistant is operating this page" shows meanwhile). It never fills password or card fields (you do, with autofill), and each send, pay or post button needs its own OK every time. Menu Machine › The Assistant in the Mac's Browser… › Stop refuses all of it at once. NanumOS' Settings › Sharing only shows this state (the Mac app is where it changes).
- Hear and Read on the Mac (on by default): when you talk to the Assistant, your words become text on this Mac only, and the Mac reads the answers with the Nanum voice 「Minseo」 — the same reading program (
speak) and voice files as inside NanumOS, run by the Mac itself, so it sounds exactly like Minseo inside NanumOS (first sound about 0.3–0.6 s). Pick the voice in NanumOS' Settings › Apps › Assistant 「Voice」 (Minseo, Junho, Sua, Jihun; Minseo also bright, surprised, worried, annoyed). The Mac's own voice reads only with 「Read with the Mac's voice」 on, and English sentences are read by the Mac's voice for now (there is no English Nanum voice yet); an app without the voice files (the public one) reads with the Mac's voice. No sound goes into NanumOS or to any server; only a line of text crosses — like an interpreter who listens beside you and hands over a note. The first time you press talk, the Mac asks once whether it may use the microphone and speech recognition. Start talking while it reads and the reading pauses within 0.3 s; keep talking and it ends the reading and takes your words as the next question. A short 「yes」/「mm」 or a cough lets it go on from where it paused (decided by length only, never by which word it was). Its own voice from the Mac's speaker is removed by the microphone's echo cancellation, and what is left is compared with what the Mac just played, so it does not stop for itself. When you stop talking, about 0.55 s of quiet ends your turn and the answer is asked for at once. Machine › Hear and Read on the Mac turns it off: NanumOS then listens (voice server) and reads by itself, as before. NanumOS' Settings › Sharing only shows the state. Now: press the Assistant button (or Command-J) and say "Open Notepad". - Devices for NanumOS (on by default): NanumOS may ask the Mac app for help with heavy work (the graphics chip for drawing and computing, video decoding). The asks travel only on one private channel between the app and NanumOS (vsock — one virtual device, not the network), and only the "desks" the app opened answer (one service per port number). Each desk has limits (connections at once, bytes each way, silent time); past one, that connection is closed. Your Mac's files and apps are not reachable this way. Machine › Devices for NanumOS… › Turn Off refuses every new ask and ends the open ones at once; NanumOS then does the work on its own processor. Try it:
vsock echoin NanumOS' Terminal — when the app's echo desk returns 64 KB unchanged you seeVSOCK echo ok. - Mac apps NanumOS may open (empty by default): Machine › Mac Apps NanumOS May Open… is a list you fill, for example KakaoTalk. NanumOS' Mac Apps window (or the assistant, without a card) can then ask this app to open that Mac app or bring it forward, and says "Opened KakaoTalk on the Mac". The ask is one short line with the app's bundle id; this app checks that the id is on your list and is not a bank or finance app, writes the request to a log on your Mac, and only then calls macOS. Banking and finance apps (a list of known Korean banks and securities firms, ids that name a bank, apps that declare the finance category) are never opened and cannot be added: open them on the Mac yourself. Nothing of the app's window or data reaches NanumOS.
Which keys go where
| Keys | Go to | Why |
|---|---|---|
| Command-Shift-3 / 4 / 5 (also with Control) | the Mac | the screenshots Mac people always use; the NanumOS window is in the picture |
| Option-Command-Q · Command-H | the Mac app's menu | Quit (saves and shuts down) · Hide |
| Command-Q | NanumOS | closes the app in front (the video player too) — pressed the Mac way, it never powers NanumOS off |
| Control-Command-F | the Mac app's menu | Full screen |
| Command-Tab | NanumOS | NanumOS' app switcher (a Mac keyboard's Command is NanumOS' Super). To reach other Mac apps: Command-H or click another window. |
| Command-Space | NanumOS | a tap = NanumOS search, held = the assistant |
| Command-Option-Esc | NanumOS | NanumOS' Force Quit |
| Control-arrows · every other key | NanumOS | word 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
- Apple's built-in virtualization makes the virtual hardware; the chip runs NanumOS directly.
- 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.
- A file with a name already there is never overwritten; it becomes "name 2".
- 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.
- 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.
- 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