Userland
Commands are ELFs. The shell is a dispatcher.
Ring-3 programs are static ELFs linked at 0x40000000.
The shell resolves a command name against builtins, the per-terminal
PATH and the kernel command registry, then spawns it with one
argument string. The command pack supplies 47 PATH commands by default.
Ring-3 model
A user process gets a page directory cloned from the kernel identity
map, a 4 MB image/stack window at 0x40000000, an optional
4 MB canvas at 0x50000000 and a growable heap at
0x60000000. The kernel remains mapped because paging is
identity-mapped; this is isolation in privilege level only, not a
separate address space.
- Optional libc. Commands include ucmd_lib.h for syscall wrappers; commands that need allocation or standard string/stdlib functions link the in-tree libc.a.
- One argument. The shell passes the raw remainder of the line as a C string at the top of the user stack;
_start(const char *arg)needs no crt0. - Inherited context. Each process inherits the spawning terminal's cwd and TTY id; the file syscalls resolve relative paths against the PCB cwd.
- Page-fault policy. A ring-3 fault kills the process and prints a short message; it does not halt the kernel.
Not a sandbox. Because physical and virtual addresses are identical and the kernel is mapped, a ring-3 bug can read or write any mapped kernel page. The privilege boundary protects against accidental corruption from ordinary code, not against malicious code.
Ring-3 libc
libc.a is optional: the Makefile links it
only into commands that reference it, and the archive plus
--gc-sections keeps unused members and functions out of
the legacy command pack. The headers live in
libc/include/ and cover
stddef, stdint, stdarg,
stdlib, string, ctype,
assert, setjmp, errno,
stdio, math, time,
sys/time, sys/types, float,
limits, inttypes, alloca
and the OS-specific ucmd_heap.h.
- malloc. Boundary-tag blocks, first-fit free
list, immediate coalescing, 16-byte alignment. The heap maps 64 KB
on first use and grows in page-rounded steps with 64 KB slack up to
the 64 MB
SYS_MEM_*arena cap;calloczeroes andreallocgrows in place when the next block is free. - heap_reset. Discards every allocation and unmaps the whole arena. Page-scoped programs such as the browser use it on navigation instead of tracking individual frees.
- Ownership. Commands allocate through libc
malloc; theSYS_MEM_ALLOC/GROW/FREEsyscalls are the backend in libc/ucmd_mem.c and are not called by application code. - stdio.
printf,snprintf,sprintfandvfprintfshare an exact decimal float formatter (%f/%e/%g, width/precision), andfopen("rb")provides read-only whole-fileFILEobjects withfread/fseek/ftell/fclose. stdout and stderr are console streams; stdin is EOF. There is no kernel fd layer yet: thestdio_file.cTODO records the futureSYS_OPEN/READ/WRITE/LSEEK/CLOSEreplacement. - time.
time,gmtime,localtime,mktime,strftime,gettimeofday/settimeofdayandclock_gettimeuseSYS_RTC_GET/SET.time_tis 64-bit, local time is UTC-only, and the RTC's 1970-2069 range is enforced. - math. The set QuickJS needs is provided with x87
double arithmetic:
sqrt,pow,exp/log, trig,floor/ceil/round,fmod,ldexp/frexpand the IEEE predicates. It is a compact double-rounding implementation, not a full fdlibm. - Limits. No threads or locking, no
free()-to-page unmap, and requests near 64 MB fail because headers are charged against the same arena. The file layer is read-only and whole-file (4 MB cap); writable files and streaming need the kernel fd layer. There is no timezone database and nolong double/%asupport. - Tests.
make test-libccovers the malloc arena, format/dtoa, math, 64-bit division helpers andsetjmp/longjmpon the host.
Spawn path
bin/<name> changes behaviour without editing the
kernel. Builtins are handled inline, before either lookup.
Syscall ABI
The gate is int 0x80. eax carries the
number, ebx/ecx/edx the first
three arguments, and the negative SYS_E* codes are
stable. The wrappers in ucmd_lib.h cover
zero to three arguments.
| Group | Numbers | Purpose |
|---|---|---|
| Console & time | 1–4, 56, 69, 104–105 | putstr, ticks, sleep, exit, RTC time/date get/set |
| Files | 5–11, 48, 98 | whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat |
| System info | 12–16, 49–51, 91–92, 102–103, 107 | memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC sensors, Chrome EC sensors, AC/battery |
| Network | 17–47, 106 | NIC config/acquire, raw frames, DHCP/DNS/NTP, TCP client, ARP, cwd |
| Window & WM | 55, 57–72, 80, 83–87, 109 | key poll, WM attach/info/map/present/create_term, window create/present/input/resize/scroll |
| Process & memory | 73–79, 81, 88–90, 108 | TTY, spawn, getpid, alive, kill, chdir, scheduler info, heap alloc/grow/free |
| TCP server | 93–97, 99–101 | listen, accept, server recv/send/close, peer, speed, MAC set |
| WiFi | 110 | SYS_WIFI(op, a2, a3): up, status, scan/results, connect/disconnect, EAPOL RX/TX, set key, authorize, set/get PTK for the rekey helper (wifi.c) |
| NIC menu | 111–112 | SYS_NET_DEVLIST (present drivers with kind/active/link) and SYS_NET_SELECT (make a named netdev active) |
The file service is whole-file, not stream-oriented. The network
service has a per-process TCP client table (up to twelve connections)
and a separate raw NIC lease for packet-level commands. There is no
fork, exec or shared memory: a command
either runs as its own process from an ELF or calls a kernel command.
Shell & PATH
The windowed shell is ucmd_term.c; the
kernel-side terminal.c holds the privileged
command registry used through SYS_SPAWN_KCMD. There is
no kernel terminal fallback; the WM spawns the first terminal once
storage is ready. Each terminal has a current working directory and
a PATH (default /ramfs/bin). Pressing Tab completes
builtin and PATH names; help lists both.
- Dispatch order. Builtins → PATH file → kernel command. A PATH hit loads the ELF through the VFS and spawns it as ring 3.
- Builtins.
cd,path,help,clear; the ring-3 shell also handlespsandkillinline.bootlogis a kernel command. - Arguments. The raw remainder of the line is passed verbatim; commands parse their own flags.
- Working directory. The prompt shows
[dir] >;cdchanges only the current terminal's cwd, and spawned commands inherit it. - Windows. A window receives keys through its window key queue (
SYS_WIN_KEY_WAIT) or the genericSYS_KEY_POLL; closing the window kills its owner process.
Kernel commands
These commands must run in ring 0 or inline in the shell; they are not files in the pack. The split keeps privileged hardware access out of ring 3 while most user-facing tools remain replaceable ELFs.
| Group | Commands |
|---|---|
| Shell | cd path help clear bootlog |
| Process / scheduler | ps sched renice kill idle cpufreq power |
| Hardware / debug | display gfxbench lsusb lspci peek poke format install dbg serial |
| Network control | netdev |
| Boot / power | reboot poweroff kexec |
format <device> [size] creates a FAT filesystem.
install <target> [source|self] installs NebOS.
With a source it auto-detects a disk whose MBR and LBA-63 boot
sector carry the NebOS signature (preferring usb0),
reads P1..P3 into RAM, creates or keeps the NEBOSDATA
partition at LBA 34816, writes the target from RAM, merges the data
entry into the MBR, writes the MBR last and verifies the result. A
source-read failure leaves the target untouched. self
writes the running gzip pack and its bundled kernel without a USB
stick; auto picks the only non-USB NebOS disk. The
data partition survives both forms, while the P1..P3 OS image and
the app pack are replaced. Both the BIOS and UEFI paths are cloned
on a full install; a later self-update leaves the ESP alone.
Command pack
The pack is built from the UCMDS list in the Makefile as
bin/<name>, plus hello and the real
browser.app and gallery.app. It is mounted
read-only at /ramfs; the shell's default PATH points at
/ramfs/bin.
Files & text
ls cat save rm mkdir rmdir edit files view
System
cpuinfo meminfo storage top mouseinfo touchpad sensors powerinfo date spin clock colors
Network
netinfo netip netdns host dhcp ping pong netsend netrecv netlog netconsole netregs netloop netreset net100 netmac curl websrv wifi netmenu
GUI
wm term files view mines solitaire gallery browser chat clock colors settime
The launchers bin/browser and bin/gallery
forward their argument and cwd, and prefer a development copy under
/share (BROWSER or GALLERY)
before the pack copy and the FAT fallback on root.img.
This lets make browser-dev and make gallery-dev
update an app without rebuilding the pack.
GUI applications
- files — browser for the VFS; opens text in
edit, images inview, HTML inbrowser. First user of ngui. - gallery — live widget and primitive showcase; the real app ships in the pack.
- chat — native Cloudron Chat client (top-bar Chat button, or
chat [config-path]): username/password/TOTP login through the Cloudron OIDC API or a pasted session cookie, channels and DMs with unread badges and presence, history with older paging, sending, REST polling, read markers, browse/join and new DM. The session cookie (never the password) is saved in/data/CHAT.CFGwhen the persistent volume is mounted, or in the RAM-only/share/chat.cfgotherwise. Keys: Enter sends, PgUp/PgDn scroll, Home at the top pages in older history, Ctrl+B browse, Ctrl+N new DM, Ctrl+R refresh, and with the composer unfocused (Esc) Up/Down switch conversations. See Network → Chat client. - solitaire — Klondike with drag-and-drop, scoring and a win animation.
- mines — second ngui canvas app; shares the toolkit and event model.
- view — fit/1:1/zoom/pan image viewer, animated GIF playback.
- edit — text editor that draws its own text with the 8x16 font.
- clock / colors — small window canvas demos.
- settime — Date & Time editor opened by clicking the top-bar clock. It reads and writes the CMOS RTC through
SYS_RTC_GET/SYS_RTC_SET; the Sync NTP button asks the kernel's SNTP client (SYS_NTP_SYNC, 106) for UTC and writes the result to the RTC. The two-digit RTC year is expanded over 1970–2069 so dead-battery defaults such as 1980/1990 can be corrected. - netmenu — network menu opened by the top-bar status icon. Lists the present NICs from
SYS_NET_DEVLIST(Ethernet, USB Ethernet, RNDIS tethering), selects one withSYS_NET_SELECTand runs DHCP. Its WiFi section scans throughSYS_WIFI_SCAN/RESULTS, asks for a WPA2 passphrase when the network is not saved and starts thewifihelper through a/share/netmenu.wifirequest, because the 64-byteSYS_SPAWNargument cannot hold a long SSID plus passphrase. Networks in/data/WIFI.CFGare marked saved and join with the stored passphrase; a Saved view lists them with a Forget button each. On success the helper moves the SSID/passphrase to the front of the saved list; the next boot'swifi autoconnecthelper joins any saved network found. Duplicate BSSIDs for one SSID are collapsed to the strongest entry (or the active one), and hidden networks are omitted. - wm / term — the ring-3 window manager and terminal launcher used by the desktop.
The WM chrome, ngui labels and the browser use the fixed-point
TrueType engine in ufont.c with the Arimo
and Liberation Mono subsets in the pack. CSS and ngui can select
regular/bold/italic/mono faces at 8–48 px; missing faces fall back to
the 8×16 bitmap. UTF-8 text APIs additionally fall back to the
monochrome Noto Emoji subset for common emoji (format-12 cmap);
the browser still uses the Latin-1 byte path. Terminal contents and
the editor stay bitmap;
ngui text fields use the proportional face for text, caret,
selection and horizontal scrolling. The browser detaches the font
arena before heap_reset() and reattaches after the page
heap is mapped.
Browser
The real browser is bin/browser.app in the pack. It links
ngui, the image library, inflate, TLS, uhttp and the vendored QuickJS
engine. It opens at 1100×700 (960×640 and 780×540 fallbacks on
smaller screens), with a URL bar, history, a status bar, inline
images and inline/external scripts. Network work runs in up to four
headless curl __serve workers, each with its own files
under /share, so the UI keeps drawing and scrolling
while several TCP/TLS connections are in flight.
- HTML/CSS subset. External and inline stylesheets; one selector engine for the cascade,
querySelector(All)andmatches(type/class/id, attribute values with= ~= |= ^= $= *=and theiflag, descendant/>/+/~combinators,:root,:link, first/last/only child and of-type,:nth-child/:nth-last-child/:nth-of-type/:nth-last-of-type,:empty,:checked,:disabled/:enabled,:required/:optional,:not/:is/:wherewith selector lists and:has);::before/::aftergenerated text (strings,attr(), quotes) emitted as literal runs that scripts never see; colours (including legacybgcolorattributes), backgrounds (solid andbackground-imagewith repeat/position/size and thebackgroundshorthand URL), realfont-size(8–48 px), thefontshorthand, bold/italic faces,font-family: monospaceand one regular@font-faceface per family (local or HTTP TTF), margins/padding (percentage sizes use the containing width;emuses the element font), per-side borders, alignment, explicit/percentage block widths withmin-width/max-width/min-height/max-height,box-sizing: border-box,margin: 0 auto, nestedem/remsizes, basic floats,position: relative/absolute/fixed/sticky(top/bottom, containing-block clamp),right/bottom,z-index(including relative boxes),overflow: hiddenclipping,transform: translate/scale/rotatewithtransform-origin(paint-time box and image transforms), flex rows with grow/wrap/justify (includingspace-evenly)/align, two-column grids, table rowspan/colspan and percentage columns,calc(percent ± px)in widths, margins/padding, heights and min/max,white-space: nowrapand@mediablocks evaluated at the browser canvas width when the page is parsed. Text is Latin-1; there is no shaping, bidi, WOFF/unicode-range or full-Unicode fallback. - JavaScript. Inline and external
<script src>blocks run on the vendored QuickJS engine (2026-06-04, ES2025: classes and private fields, arrow functions,let/const, template literals, destructuring, spread, async/await, Promise, Map/Set, BigInt, optional chaining) in document order.js_mu.ckeeps the MuJS-style value-stack API the DOM layer was written against, runs outermost engine entries on a private 1 MB stack (the ring-3 stack is 128 KB) and drains Promise jobs after each script, timer and event. External scripts use the same local/network fetch path as pages and CSS (512 KB cap) and are cached under/share/bjs-*for the current boot; the parsed page is painted before scripts run. Classic scripts are sloppy by default. Math, Date and JSON are the engine's; each page gets one state, and a 20 s wall-clock budget per script, timer or event turns a runaway loop into anInternalError: interruptedinstead of freezing the browser. The Cloudron app store (AngularJS 1.3, a 666 KB inline catalogue and an ES2015 controller) renders its hero carousel, 26 sections and 308 cards. - DOM. Nodes are interned userdata wrappers that inherit from
Object.prototype, so===and library expando caches behave. Elements supportgetAttribute/setAttribute/hasAttribute,appendChild/insertBefore/removeChild/replaceChild/cloneNode/remove,querySelector(All),getElementsByTagName,getElementsByClassName,classList,dataset, inlinestyle(cssText, property get/set,getPropertyValue/setProperty/removeProperty),innerHTML(fragment parser),textContent/nodeValue, traversal,matchesandgetBoundingClientRect(real block/table/absolute/image boxes; inline text boxes are still approximate). Form controls expose livevalue/checked/selectedIndexproperties backed by the browser's control state; forms exposeelements,submit()andreset(), and elements dispatch realaddEventListener/dispatchEventevents with capture, bubbling andpreventDefault().<a>elements exposehref/protocol/host/hostname/port/pathname/search/hash/originresolved against the page URL.documenthascreateElement,createTextNode,createComment,createDocumentFragment,createAttribute,documentElement/body/headandreadyState;navigator,history,matchMedia,getComputedStyle,setTimeout/setInterval/clearTimeoutandrequestAnimationFrameexist, and due timers are pumped from the browser loop. jQuery 1.11, Bootstrap 3.2 tooltips and AngularJS 1.3 (with ngRoute/ngSanitize) initialize on a local test page. - Not supported. Inline event attributes (
onclick=),MouseEvent/CustomEventandonce/passivelistener options,type="module",defer/async,MutationObserver/IntersectionObserver,XMLHttpRequest/fetch,DOMParser, canvas/2D contexts, user-state pseudo-classes (:hover,:focus; their rules are dropped at parse time) and pseudo-elements other than::before/::after. Basic controls render, focus, edit, toggle, select, submit GET queries and POSTapplication/x-www-form-urlencodedbodies (see the compatibility ladder);getComputedStylecovers the engine's properties, andouterHTMLonly returns the string last assigned toinnerHTML. - CSS gaps. Multiple background layers and
background-attachment(a non-uniformbackground-sizeuses the width scale), 3D/perspective transforms and transformed text/descendants (scale/rotate paint the box and inline images), generated-content boxes (::before/::afterare text only: no background, counters orurl(), and none inside flex/grid containers),bottom/percentageleftplacement of nested absolute boxes, border-radius clipping of descendants, gradients/box-shadow/transitions andcolor-mix. Flex rows, card grids, tables with rowspan/colspan, inline SVG and CSS variables are supported. - Inline SVG. svg_raster.c flattens every path command (curves and arcs included), rects, circles, ellipses, lines, polylines and polygons through
transformlists and the viewBox mapping, then fills (nonzero or even-odd) and strokes them with antialiased coverage into an RGB565 + alpha layer cached per node and size.<g>, nested<svg>,<use>of a<symbol>, opacity,currentColorand inheritedfill/strokework; a gradient paints the average of its stops, and patterns, clip paths, masks, filters and markers are not rendered. SVG paint has its own style state, so CSSfillon an HTML element no longer paints its background. - Caps. 2 MB page body, 832 KB CSS, 6144 DOM nodes, 4608 rules, 16 images. Each image gets an
img_estimate()-sized decode arena that is freed after the scaled bitmap is made; navigation callsheap_reset()and unmaps the page heap. - Fetching. Up to four worker processes prefetch images in parallel within the viewport plus 160 px; each worker keeps its own TCP/TLS connection and its own request/body/meta files (keyed by browser pid and worker slot, so multiple windows do not collide). Completed images are decoded as jobs finish. Stylesheet and external-script bodies are downloaded in parallel but parsed/executed in document order, and one image starts before the script phase so it overlaps script loading. Idle helpers stay warm for same-origin navigations (they exit after ten idle seconds, and losing window focus stops them), while a cross-origin navigation closes them first so the old page's connections cannot stall the new fetch. A DNS failure is retried once. While loading, the status bar reports the page fetch's header and first-byte times; when the load is done it shows
Loaded in N ms: page P (headers H), parse, css, paint, jsfor 12 s. On the Cloudron store under QEMU/TCG with e1000 that is 2572 ms, of which the scripts take 1911 ms; QuickJS is built-O1, which beat-Osand-O2there. - URL entry. A dotted name without a scheme that is not a known local file extension is treated as a hostname, so
cloudron.iodoes not hit the local-file stat. A typed hostname is tried ashttps://first, skipping the commonhttp://host→https://hosthop; if the https connection is refused, reset, times out or fails the TLS handshake, the browser retries once overhttp://and replaces the history entry. Origin-level redirects (such ashttps://host→https://www.host) are cached per process and in/share/borigins; the first visit still follows them, later visits go straight to the canonical origin. Remote stylesheets are cached under/share/bcss-*for the current boot, so a reload or a fresh browser launch skips the CSS downloads.
The browser's default canvas is dark, matching the ngui theme, but an
html/body background fills the whole page
canvas. Pages without one that set dark text can be hard to read;
pages with their own background and colour rules are unaffected. See Graphics → Image
library for the decoder limits.
testdata/browser/compat/ is the browser compatibility
ladder: numbered, self-contained pages with an A/B pair for each
behaviour. Run make compat-serve and open
http://<host>:8000/ on the board (or
http://10.0.2.2:8000/ in QEMU's user network). The
index records the current pass/fail status; pages 010–070 and 030a pass
(036a needs the POST echo server), while
the README lists the remaining gaps.
Source map
syscall.c,syscall_stub.S,syscall.hsys_info.c— kernel-state snapshots (memory, sensors, power)rtc.c— CMOS RTC read/write, format decoding and the 1970–2069 year windowprocess.c— ELF load and spawnelf.c— ELF parserucmd_term.c— windowed shell, scrollback, PATHterminal.c— privileged kernel command registryinstall.c— privileged live-image clone installerucmd_lib.h— user shimlibc/— headers, malloc, string/stdlib, setjmp/errno, stdio/dtoa, math, time and theSYS_MEM_*backendlibc.a— optional static ring-3 libcucmd.ld— ring-3 link addressMakefile—UCMDSand pack rulesucmd_*.c— commandsufont.c,ufont_ttf.c— fixed-point TrueType textngui.c— GUI toolkit;fonts/*.ttf— UI and emoji subsetsbrowser.c,browser_html.c,svg_raster.c/h(+svg_test.c),js_browser.c/h,js_mu.c/h,third_party/quickjs/,gallery.cucmd_chat.c,chat_login.c,ujson.c,uhttp_cookie.c— chat clientucmd_wifi.c,wpa.c,wpa_crypto.c—wificommand and the WPA2-PSK supplicantucmd_netmenu.c,wifi_cfg.h,wifi_store.c/h— top-bar network menu, staged WiFi connect record and saved-network list