Reference
The WolOS Reference.
The developer documentation of WolOS: how the system is built, every wol command and keyboard shortcut, the UI kit and the decisions behind the design. For using WolOS, read the Manual.
Desktop and system
- SoundOne sound server with rules that keep microphones from clipping, low latency where it matters, and a choice of Bluetooth codecs.
- Sound for creatorsRecording, streaming and producing: buffers, OBS, a separate game track, DAWs.
- GamesNative Steam with Proton, and Windows programs outside Steam on Wine.
- Power and sleepThe power source picks the profile; Low Power and High Power Mode override it.
- Hardware and driversOne catalogue decides the driver, firmware and options for each device.
- wopkg: one tool for every sourcepacman repositories, Flatpak, AppImages, recipes and community packages behind one command.
- Packages and pinned repositoriespacman is the package manager; every repository is pinned to the release.
- Community package lawsEach community package is read as a graph and checked against named laws before it installs.
- Optional modulesAI, developer, creative and console stacks, installed after the base and removable.
- Plugin API referenceThe complete manifest, permissions and Lua API for shell plugins.
- Desktop widgetsClock, calendar, weather, music, batteries and system cards on the desktop.
- Plugin Maker and Theme StudioMake a plugin or a theme and see it live in a sandbox, then package it for the plugin index.
- wol-hue: themes from a pictureTurn a picture, a Base16 scheme or a colors.toml palette into an ordinary theme that always passes the contrast rules.
- Themes in every appOne theme switch restyles GTK 3, GTK 4, Qt, the browser, the terminal and the shell prompt.
- Boot and install safetyTwo system slots, signed boot images, quiet boot, and an installer that only touches what it planned.
- SecurityFirewall, hardening, daily update checks, a first-use malware check and disk encryption.
- Assistants and automationScripts and AI helpers act through the same `wol` commands as people, behind an approval gate.
- System APIWhat the shell and `wol sys` read about the machine, and the rules that keep reads cheap.
- Testing the whole system in a VMwolvm boots the ISO, goes through the installer and drives the installed desktop, step by step.
- libwol: the app APIOne stable C ABI for apps in any language: windows, menus, notifications, files, power and more.
- The window serverThe WolOS patches to the window server for frame pacing, idle cost and window behaviour.
- WolKernelLinux 7.3 with a small series of foreground and gaming patches, each with an off switch.
- Performance budgetsIdle cost and response times of the desktop, with targets and measurements.
Apps and the UI kit
- Interface guidelinesThe binding rules every WolOS app follows: one scaffold, tokens, behaviour.
- Cryswol: every system verb in CrystalThe Crystal shard that gives an app windows, notifications, files, power, network, Search and the other system verbs, as typed objects.
- Your first Wolkit appA to-do list in eight short steps: a window, a text field, a list, a style sheet, a test without a display and a package.
- Wolkit: the UI kitViews from signals, components, the interface guideline parts, a navigator, services and a test harness, in one Crystal shard.
- Wolkit style (.wolcss)A small style language whose values are theme tokens, compiled ahead of time and checked for mistakes.
- Crystal shards and wol shardOne signed list of Crystal libraries, each pinned to one commit, and the commands that write the pins and the lock for you.
- Scripts: sh, bash and RubyCheck and run a shell or Ruby script the same way, as you, through the same approval gate as every helper.
- Bundled appsThe apps that come with WolOS, rebuilt in Crystal on Cryswol and Wolkit, and the rules every one of them follows.
- GalleryThe picture library and viewer of WolOS, and the first bundled app in Crystal on Wolkit.
- Crystal rules (RCR)The rules every Crystal file in WolOS follows, the standard library policy, the pinned toolchain and the advisories list.
- libWolkit: the UI engineThe engine under Wolkit: scene, style, layout, text, paint, input and accessibility, behind a small versioned C interface.
- Wolkit benchmarksHow the UI kit is measured, the budgets it must stay under, and every number measured so far with its machine.
Commands and keys
Decisions
- 0016: Arch Linux base, in snapshotsWhy WolOS is built on the base distribution's packages pinned to a dated snapshot.
- 0017: One base systemWolKernel and the base userland are released together, as one version.
- 0021: wopkgOne package tool for every source, with a stable library behind it.
- 0022: Community packages judged by lawsCommunity packages are judged by named laws over graphs, never called safe.
- 0023: Installer plansThe installer writes a plan, and the plan names everything it may touch.
- 0024: First-use malware checkFiles are checked the first time they run, instead of a crawler that reads the whole disk.
- 0025: Signed boot with this computer's keysEach computer makes its own boot keys at install; no shared vendor key.
- 0026: Memory SaverBackground apps give memory back and take it again as they run.
- 0027: One app cannot take the desktopPer-app limits keep the session responsive when one app runs away.
- 0028: The full signature engine in its own processFull signatures are optional, fetched by you, and run apart from the guard.
- 0029: Repository splitCode, recipes and the image live apart, and there is one build path.
- 0030: Package repo on a CDNThe package repo sits behind a CDN with the release host as fallback; the x86-64-v3 repos are reached by redirect, not copied.
- 0031: Plugins, themes and layoutsFolder plugins in a sandbox, themes for every toolkit, and layouts as data.
- 0032: Optional modulesAI, developer, creative and console stacks as removable modules and Kits.
- 0033: The system service greets firstApps are identified the moment they connect, and both sides confirm each other before any request.
- 0034: Locally built packagesA package built on this computer is staged in a root-only folder and installed only after you confirm.
- 0035: Live layers on a slot switchPackages added live are held, not merged, until the new system copy has started well.
- 0036: Crystal is the userland languageOne language for apps, tools and integrations, with generated bindings over the stable C ABI.
- 0037: Who may show a sheetProposed: only the shell the system service started for your session may show and answer approval sheets, not any process that runs the same file.
- 0038: One sound service, and 100% is 0 dBOne sound service sets every volume on one scale, where 100% is the device's own 0 dB, so a new microphone no longer clips.
- 0039: libWolkit and WolkitA Rust engine draws the window; a Crystal shard owns views, signals and the tools; patches and events cross between them as data.
- 0040: Security defaults on LinuxFirewall on, no remote login, updates found without asking, and app permissions that say how they are enforced.
- 0041: Ruby scripts run like shell scriptsA Ruby script is checked and run the same way as a shell script, as the person, through the helper gate.
Also on the site
- Files and foldersFind, open, copy, move, rename and delete your files in Files, get them back from the Trash, and check one…
- Your first Ruby scriptWrite a small Ruby script in a text editor, check it with wol script check, run it with wol script run, and…
- What a terminal isThe window where you type instead of click: what the prompt, a command, an argument and a path are, how to…
- System SettingsThe one window for everything you can change: how to open it, find any setting by typing, what every pane…
- zsh basicsThe shell in every WolOS terminal: history, Tab, suggestions, the colours of a command line, wildcards…
- The desktopThe menu bar, the Dock, windows, Search, switching apps and the four desktops: what each part of the screen…