Commands and observations connect the boot process, causal history, applications, and source code. This continuous edition can be printed for use during a SlOS session.
Native boot, ELF64/LP64, the application workbench and SMP references are current. The application guide expands the editing, versioning and recovery workflow. Older graphical commands and source walkthroughs retain their i386 scope.
| Order | Route | Use |
|---|---|---|
| 0 | First run | Diagnose native 64-bit prerequisites, verify persistence, boot a disposable QEMU VM, and learn shutdown keys. |
| 0a | Building SlOS | Native architectures, build tools, user SDK and operating limits. |
| 0b | Local Hew | Slepp’s personal compiled-Hew experiment and explicit runtime subset; not official Hew support. |
| 0c | Applications | C/Hew workbench, editor, diagnostics, ledger, job queue, installed reports and saved-project recovery. |
| 0d | Distributed computing | Narrated native render sessions, worker loss and accepted-result recovery. |
| 0e | Durable debugger | Follow application receipts across machines and boots, keeping offline evidence historical. |
| 1 | Overview | Native kernels, user applications and causal history, with explicitly historical showcase recordings. |
| 2 | Manual | Read the structured reference before operating: identity, history, time travel, web explorer, apps, commands, and source map. |
| 3 | Causality laboratory | Study event records, Lamport time, parent edges, replay, journal proofs, and federation. |
| 4 | Subsystem chapters | Read each subsystem with its role, source files, and command that makes it visible. |
| 5 | Source excerpts | Dated examples from causal.c, cjournal.c, replay.c, httpd.c, scrub.c, and timeline.c, with a current file atlas. |
| 6 | Glossary and source atlas | Pair terms with implementation files before changing vocabulary or explaining internals. |
| 7 | Execution walks | Follow prompt-to-device and prompt-to-graph paths with transcripts. |
| 8 | Operator labs | Run QEMU exercises and compare expected observations with live output, including remote-shell operation. |
| 9 | Showcase | Watch recorded sessions and map each clip to commands and source. |
| 10 | Showcase notes | Use chapter notes as prompts for live reproduction. |
| 11 | Reading room | Place the design beside logical clocks, event sourcing, provenance, actors, and time-travel debugging. |
| 12 | Field manual | Print this continuous route and use it beside the running kernel. |
SlOS records kernel and application activity as causal events, allowing commands to inspect what changed, which earlier events caused it, and what followed.
Recent events are queried from a live ring, while cjournal preserves selected history on disk. cwatch streams new activity; scrub and /causal expose replay and graph inspection. The wm desktop displays CPU and system panels, and telnetd or noiseshd provide remote terminal sessions.
Start with make doctor, make first-user-check, then make dev. The host-native 64-bit target uses DOOM=0, a fresh disposable disk, serial I/O, and no host forwards. Native QEMU SMP defaults to four CPUs. DEV_MODE=graphical adds a VGA window on x86-64 only; DEV_DISK=my-slos.img requests persistence. Successful disposable sessions remove their image; failures retain it. Type halt or Ctrl-a x to exit; /start has prerequisites.
For remote access, /start documents explicit loopback SLOS_QEMU_HOSTFWD rules with a persistent DEV_DISK. The legacy run-nographic workflow instead reuses disk.img and opens its standard host forwards beyond loopback. Older operator labs retain that workflow and their historical application scope. Start the intended guest service separately.
An event has an ID, node hash, Lamport time, wall tick, type, subsystem, description, optional payload, schema data, and up to four parents. Parent IDs turn logs into a DAG.
Use events, why, trace, graph, blast, cpath, and cdot for the hot graph. Use events -a, cq -a, why -a, and trace -a when the answer must read through durable journal segments.
cjournal persists causal events to SlFS segments. The journal records segment indexes, event hashes, Merkle roots, and proof material so archived history can be queried and checked.
Use journal recent, find, type, subsystem, stats, filter, verify, json, selfcheck, proof-health, and epoch-proof. Use cq selectors for typed query work: type=, subsystem=, desc~, since=, until=, id=, segment=, and limit=.
Replay reconstructs state by scanning events forward to a tick. scrub makes this operator-visible: scrub for a TUI, scrub <tick> for a single frame, scrub event for focus, scrub diff for deltas, and scrub json for machine-readable state.
whatif is counterfactual rather than restorative. It asks which downstream effects would be eliminated if one event were dropped from analysis.
Under the default QEMU run, telnetd is reachable from the host at localhost:2323 and noiseshd at localhost:5200. On real hardware or bridged networking, use guest ports 23 and 5200. The encrypted path uses the host script scripts/noise-shell-client.py.
Telnet is unencrypted, and the Noise shell does not authenticate the server; neither is OpenSSH. Terminal redirection provides ANSI output, cooked-key input, telnet NAWS sizing, and remote full-screen editing. Filesystem commands use the same namespace, and detached services can survive disconnect.
Timelines provide common controls for graph-native applications: tl list, show, rewind, forward, at, mark, and tail. Notes, mail, editor, process views, and scheduled commands build on this model.
Actors, mesh, and federation expose named message endpoints, routes, encrypted peer channels, and remote graph or actor delivery. Use actors, send, recv, routes, mesh, federation, ping, netstat, and arp as field instruments.
Use make development-console to open a fresh native workbench with the editor, develop client and trusted host compiler worker. Configure the worker using the printed guest command. init creates a C project; init PROJECT hew creates a real Hew actor starter when matching compiler/library/runtime inputs are supplied.
Edit declared sources, then build and run. diagnostics retains checked feedback, edit opens its safe source line, and status distinguishes current edits from selected/previous programs. A failed build does not replace the last good application. rollback selects the predecessor without restoring source or unrelated application data.
The editor uses Ctrl-S to save and Ctrl-Q to quit, with repeated confirmation for unsaved changes. Failed saves keep the modified buffer open. The buffer has no persistent recovery copy: save failures, confirmed discard and a lost guest must not be confused with saved work.
For a normal handoff, save, fsck and halt, then resume the unchanged stopped session. For an interrupted session, keep the original offline and private. Checked rescue, production replay on a new v2 copy when needed, and DEVELOPMENT_IMPORT_PROJECT start a fresh workbench with new credentials. Import and DEVELOPMENT_SESSION are mutually exclusive; only checked project files are imported.
The local Hew tools provide familiar text, filesystem, data, system and network workflows through bounded command profiles. Installed help belongs to the selected application, not the separate C rescue builtin. Use /hew for the command families and /applications for worked examples.
Ledger entries, queue state and report work live outside program-version directories. Stop a running service before an update or rollback; selecting older code does not restore its application data. The queue retains pending work and supervises two actor workers; the installed report workspace retains immutable input snapshots and checked reports.
The renderer and durable debugger are native Hew user programs. The browser displays guest work and evidence, not host-computed accepted results. Remote observations and offline caches remain distinct from verified current local state. The recorded compute tour uses labelled excerpts; the three complete sessions preserve continuous real-time execution.
x86-64 and AArch64/QEMU virt default to SMP=1 CPUS=4. Explicitly AP-pinned kernel work is preemptive; user programs, allocation, filesystems, networking and general services stay on CPU 0. Native automatic offload and user migration are not implemented; SMP=0 CPUS=1 retains UP debugging.
The older i386 cooperative offload and 1024x768 wm desktop recordings remain historical examples. Current native SMP checks prove concurrent AP work and lifecycle handling alongside a BSP user process, not multicore Hew execution or a port of every graphical application.
httpd serves both a dashboard and the /causal explorer. /causal draws a live SVG DAG and lets the reader focus events and scrub state. The companion endpoints are /api/causal/state, /api/causal/recent, /api/causal/graph, and /api/causal/dot.
The browser and shell views share the kernel event and replay interfaces. programs/httpd.c implements the page and API routes.
Installed Hew programs use their own documented CLI. Prefix a same-named history command with kcmd to select the kernel forms below; use --help for the installed program.
exec /develop.elf init /home/demo [hew] | Create a C or Hew workspace without replacing existing source. |
exec editor /home/demo/main.c | Edit source; Ctrl-S saves, Ctrl-Q protects unsaved changes. |
exec /develop.elf build /home/demo; exec /develop.elf run /home/demo | Build on the trusted host worker and execute the checked native program in SlOS. |
exec /develop.elf diagnostics /home/demo; exec /develop.elf edit /home/demo | Revisit checked compiler feedback and open its safe source location. |
exec /develop.elf status /home/demo; exec /develop.elf rollback /home/demo | Inspect program selection and choose the verified predecessor without reverting source edits. |
report accept 1 /expenses.tsv; report run 1; report status 1 | Use the separately installed report workspace; accepted input and working data survive code selection. |
exec service status; exec service stop; exec service start | Operate a prepared installed service; stop before updating its project. |
why job 1; why service | Inspect durable application evidence when the debugger bundle is installed; kcmd why selects kernel history. |
events 10 | List recent causal events. |
events -a find switch 8 | Search durable journal text. |
why --md last | Export a Markdown causal chain. |
trace -a last | Read-through ancestry from the journal. |
cq -a subsystem=sched limit=20 -l | Archive query with selectors and long output. |
journal proof-health --json-ish | Check journal proof health. |
cpath selftest; cdot last effects | Inspect causal paths and DOT output. |
ctop 128; cwatch tail; lens save demo events 5; lens run demo | Monitor activity, live-tail the graph, and reuse named causal queries. |
smp; cpus; smp test | Inspect native CPU state and exercise preemptive AP-pinned kernel work alongside a BSP user child. |
wm | Historical i386 tiled framebuffer desktop; Tab focuses panels, q/Esc exits. Not native qualification. |
cat < /input.bin | cat | cat | tee /copy.bin > /second-copy.bin | With installed external tools, up to four stages run concurrently with binary-safe input/output. All-builtin rescue composition stays buffered; mixed composition is rejected. |
telnet localhost 2323; python3 scripts/noise-shell-client.py localhost 5200 | Enter SlOS remotely: telnet is plain; noiseshd is X25519 plus ChaCha20-Poly1305 but not server-authenticated. |
termsize; edit /home/day.sl; run /home/day.sl; exit | Exercise terminal sizing, remote full-screen editor input, persistent files, slosh execution, and session close. |
mkdir /home/day; write /home/day/file persistent; write /tmp/scratch.txt volatile; cat /home/day/file | Remember the overlay rule: /home persists to SlFS, /tmp and relative paths are RAM scratch. |
chatd start; chatd status | Run the multi-user TCP chat service on host-forwarded port 6667. |
scrub event last; scrub diff 100 99999; scrub json | Inspect time-travel state. |
tl show notes; note search term; mail unread; schedule 100 events 5 | Operate timeline applications. |
httpd | Serve the web explorer, then open http://localhost:8080/causal from the host. |