NanumOS

Linux programs

How to run a program made for Linux on NanumOS without changing it: a server written in Go, or Alpine Linux's Python.

What this is

A Linux program asks the Linux kernel for things — "open this file", "accept a connection" — in Linux's own words. NanumOS understands those requests and answers them its own way, like an interpreter standing next to the program. The program believes it runs on Linux; the files, network and threads doing the work are NanumOS's.

How to use it

fetches the packages — they are not part of the NanumOS image.

How it works

  1. linux reads the program file (ELF) into memory. A program that needs package libraries also gets the root's /lib/ld-musl-..., which finds and loads the rest of the libraries.
  2. Each Linux request (system call) the program makes is taken by the NanumOS kernel and translated: files are the RAM file tree, connections NanumOS's TCP, threads NanumOS threads.
  3. The same rules as for every other program apply: it may change only files this run made or folders allowed with -w, the memory limit holds, and kill and Ctrl-C work the same.
  4. A request NanumOS cannot translate is answered "not there" (ENOSYS) and named once on the serial log as linux: ENOSYS NAME.
Technical details
  • x86-64 and AArch64. Static, static-pie, Go -buildmode=pie and Alpine's dynamic programs. Go's default build (fixed address 0x400000) is refused.
  • Child processes work: a program can start others (fork, exec, Python subprocess, Go os/exec, shell scripts with pipes). fork shares the program's memory until one side writes a page (copy-on-write: forking a 200 MB program costs about 2 MB); up to 256 programs run at the same time in the whole system, as memory allows. A child shares its parent's open files, sockets and shared memory (mmap MAP_SHARED), as on Linux.
  • Several programs can use one SQLite database at once (file locks work across programs, WAL and rollback journal).
  • Go programs are preempted like on Linux: a goroutine in a long loop no longer keeps the others waiting.
  • Signals reach a program's handlers (Ctrl-C becomes KeyboardInterrupt in Python); Ctrl-C and kill %N reach the program and every program it started. The console answers as a terminal (window size, raw keys).
  • Not yet: job control (stopping and continuing), IPv6 and named Unix sockets (a socket pair works), symbolic links, the glibc builds from nodejs.org (Alpine's Node.js 22 runs: the test linux_abi.py --only node). File names are at most 31 bytes and UTF-8.
  • lxtrace on writes every call to the serial log (like strace).
  • Contract: docs/contracts/LINUX_ABI.md.

Frequently asked

Can a Linux program start other programs? Yes. A shell script, Python's subprocess and Go's os/exec start them

Can the program see my documents? No. Nothing outside the root folder is visible; .. stops at the root.

How is this different from a Linux virtual machine? A virtual machine starts a whole Linux kernel of its own. This runs one program on NanumOS with no Linux kernel: lighter and quicker to start, but not every Linux feature is there yet.

NanumOS 0.1.8349 · 2026-11-16