Skip to content

About

A Lisp Machine–style environment on a bare Linux kernel: SBCL is PID 1 and the whole userland. A pixel-native, Smalltalk-inspired live environment on the framebuffer that browses, inspects, debugs and recompiles its own source. Includes a terminal, web browser, containers, networking and an LLM agent, all in Lisp.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

443 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

lisp-over-linux (LoL) — a live, Smalltalk-style Lisp environment that is the whole machine

LoL is an environment you work inside, in the tradition of the Lisp Machines and Smalltalk: one live Common Lisp image holds your code, your tools and the desktop they’re drawn on. Every part of it can show its own source, be inspected, be debugged with its stack standing and be redefined while it runs — the code browser, the debugger, the window system, the terminal, the editor you type in. The tool you look with is made of the same stuff as the thing you look at.

It’s the whole userland of a bare Linux kernel. SBCL is PID 1: no shell, no systemd, no X server, no toolkit. The machine boots straight into the environment, which draws every pixel itself on the framebuffer.

./media/screenshots/windows-2026-10-20.png

/As it boots, under QEMU: the Workspace tiled across the screen, a Lisp scratch buffer whose lines are verbs, and the module index (Super-m) torn off into a window with Super-g. Both are morphs in one world, drawn by the Lisp from TrueType outlines it rasterises itself. Across the top: tabs, then the systray (network, the agent and what it has spent, the clock)./

Working in it

Everything is a subject you can drill into. One protocol, present, turns any object into a view of drillable rows: a module, a package, a class, a generic function and its dispatch matrix, a condition and who signals it, a closure and what it captured, a file, a process, a web page. ↵ opens the next pane on the selection, so a trail of panes reads as the path you took. Super-Space (the Spotter) finds anything by name; Super-? lists every key.

./media/screenshots/desk-2026-10-20.png

/Live definition: C-c C-c on line 10 has compiled greet into the running image and recorded it in the change set; C-c C-p printed (greet "lisp") under itself. The status bar names the verbs: Do it, Print, Inspect, Debug, define, Ask./

  • Change it while it runs. Any source pane is live: edit a definition, C-c C-c, and it’s compiled into the image and becomes the source the browser shows. Each change is first tried in a throwaway child process, so a definition that hangs or kills its process is refused before it reaches yours.
  • A real debugger. An error stops with the stack still standing: restarts, an sb-di backtrace, frame locals you can change, a frame you can restart, M-. into any frame’s source. One restart asks the agent to explain the error.
  • An inspector with the old powers. Every instance of a class (a heap walk), why an object is still alive (the path from a root), evaluation with self bound to the object, a closure’s captured variables as settable fields (inspector-history.org).
  • A window system in the same image (Morphic). Everything on screen is a CLOS morph in one world. Super-g tears a tab off into a window you move and resize; the middle button’s halo acts on whatever is under the pointer; a row, a field or a name drags from one view into another (Super-p picks it up, Super-d drops it) (morphic.org).
  • A session that survives power-off. Every C-c C-c is journalled and replayed at the next boot; tabs, windows and the Workspace text come back; the journal view’s F files the edits back into the source files. It all lives under one ~/.lol/ tree (session-persistence.org).

./media/screenshots/debugger-2026-10-20.png

/The debugger, from the Workspace’s C-c C-d: the condition, its restarts (the last one asks the agent), the call stack, and the selected frame’s locals; degrees is settable./

The tools around the code

  • A terminal (Super-↵). A login shell in a user-namespace container over the host’s own Debian, so git, language runtimes and databases work without growing the image. The pty, the VT parser and the cell grid are Lisp.
  • A web browser (Super-b). The host’s Chrome, headless in a container, driven over the DevTools protocol; the Lisp decodes and draws its frames and turns our keys and clicks into its input. A page is a tab like any other, or a window.
  • A file manager (Super-f). Previews (PNG, GIF, JPEG, archives, ELF, hex), and the Spotter reads paths.
  • An agent. An LLM client written in Lisp, living in the image, whose tools are the image’s own introspection. Every write it wants (an eval, a definition, a file, a command) is a condition with restarts that you approve on screen; C-g stops it.
  • Networking in Lisp (DHCP, DNS, SNTP, HTTP/HTTPS, IPv6, Wi-Fi), a clipboard with history, runtime font scaling, screencasts with sound.
  • It explains its own freezes. A session log with a heartbeat, stall reports carrying every thread’s backtrace, the kernel’s log copied to disk (diagnostics.org).

./media/screenshots/browser-2026-10-20.png

/The module index: every definition in the image, grouped by the file it came from, beside the selected module’s contents. It’s the only view that shows the whole system, the toolkit included (it lives in its own lol.* packages)./

./media/screenshots/files-2026-10-20.png

The file manager, filtered to =~/Pictures=, with a JPEG previewed beside the listing.

Trying it

Build the image and boot it in a QEMU window you can type into (prerequisites are under “Rebuilding the environment from scratch” below):

./build.sh --interactive

It opens on the Workspace. Put the point after a form and use a verb (C-x C-e Do it, C-c C-p Print, C-c C-i Inspect, C-c C-d Debug). Super-Space then “tour” walks the system’s own code, stop by stop. To learn the code from outside, start at tour.org, the index of an offline HTML guide with diagrams and reading paths. The environment’s design and phase tracker is code-browser.org; the status of every piece on one page is doc/status.html.

What is underneath

The project started as the smallest Linux a UEFI machine can boot from a USB stick with no bootloader (EFISTUB, micro-distro.org); SBCL then replaced everything above the kernel (sbcl-init.org). The boot chain is still small:

firmware → the kernel (it is the EFI application) → a small C preinit → SBCL.

  • Boot source. A USB stick, or an entry in the host’s GRUB.
  • =preinit=. Mounts the host’s disk read-only except for /home, drops to the user with five capabilities, and =execve=​s the Lisp, which stays PID 1 for the life of the machine.
  • The supervisor. Leave the environment (Super-q) and you land on its console menu, with a REPL of its own.

./media/screenshots/screenshot-2026-10-20.png

/The supervisor’s menu and its REPL on the framebuffer console, with the Land of Lisp alien (the “LoL” is also a nod to Land of Lisp). Screenshots are archived per date under media/screenshots/; ./refresh-screenshot.sh re-captures them from a headless QEMU./

Every kernel option and why is in kernel-config.org. This is a learning project: the .org docs are the deliverable, written to be read, and the code is meant to be understood as much as run.

What is in this repo (and what is NOT)

Tracked here: the sources and docs — the C preinit, the Lisp modules, the initramfs description, build.sh, deps.sh, every .org write-up, and a pinned snapshot of the kernel .config under kernel/.

Not tracked (too big, version-specific): the Linux kernel source tree and the SBCL source tree. The build reaches them through two gitignored symlinks in the project root:

./linux  ->  a Linux kernel source tree   (e.g. linux-7.2.5)
./sbcl   ->  an SBCL source tree (already built)

build.sh locates itself and uses ./linux and ./sbcl; nothing hardcodes a home path, so the project folder is relocatable and clone-able by anyone.

Rebuilding the environment from scratch

You need the two symlinks above (pointing at real trees) and the host toolchain. deps.sh creates the symlinks.

1. Host packages (Debian/Ubuntu)

sudo apt install build-essential bc kmod cpio flex bison \
     libncurses-dev libelf-dev libssl-dev dwarves rsync \
     qemu-system-x86 ovmf dosfstools mtools gdisk musl-tools

2. The Linux kernel tree (./linux)

If you already have a kernel source tree:

./deps.sh link linux /path/to/linux-7.2.5

From nothing (downloads into ./sources/, symlinks, applies our pinned config):

./deps.sh kernel 7.2.5       # version defaults to the one we pin in kernel/

The pinned config is kernel/config-7.2.5 (kernel-config.org explains every option). deps.sh kernel copies it to linux/.config and runs make olddefconfig.

3. The SBCL tree (./sbcl)

If you already have a built SBCL checkout:

./deps.sh link sbcl /path/to/sbcl

From nothing (clones; you then build it — SBCL needs an existing Lisp to bootstrap):

./deps.sh sbcl
cd sbcl && sh make.sh && cd ..

build.sh expects sbcl/src/runtime/sbcl and sbcl/output/sbcl.core to exist.

4. Build

./deps.sh status        # sanity: both symlinks resolve
./build.sh              # preinit + lisp-init + initramfs.cpio   (seconds)
./build.sh --kernel     # ALSO rebuild the kernel + BOOTX64.EFI  (minutes)
./build.sh --run        # build, boot HEADLESS in QEMU/OVMF, screenshot it
./build.sh --interactive  # build, boot in a QEMU WINDOW you can type into
  • =–interactive= (=-i=) is for driving the environment, the supervisor menu and the REPL. PID 1’s console is the framebuffer VT (tty0), so you type in the QEMU window while the launching terminal mirrors the serial/kernel log.
  • =–run= boots, screenshots and kills QEMU: quick checks and CI.

Then write the USB and boot real hardware: micro-distro.org. Or skip the stick: ./build.sh --install-host puts both files in the host’s /boot/lisp for a one-time GRUB entry (micro-distro.org → Booting from the host’s GRUB).

Upgrading the kernel version

The symlink is the whole trick: point ./linux at the new tree and rebuild.

./deps.sh kernel 7.3           # download + extract + symlink + apply config
# if 7.3 has no pinned snapshot yet, configure, then:
#   cp linux/.config kernel/config-7.3    (commit it)
./build.sh --kernel

Nothing in the project needs editing; only the symlink moves.

The docs (read these)

The environment

FileWhat it covers
tour.orgStart here to learn the code. Index of the HTML guide (doc/guide/: diagrams of the boot, build, module graph, present, pixels and input; reading paths; glossary; exercises) and of the in-image tour.
code-browser.orgThe environment’s design and phase tracker: the present drill-down protocol, the accordion shell, trails/tabs/Spotter, live editing, the debugger.
morphic.orgMorphic: morphs as CLOS objects in one world, damage repair, trail windows (SuperL-g), the halo, overlays and stepping, every pane and its body a morph, drag and drop through the hand.
session-persistence.orgHow a session is kept: the per-Accept journal replayed at boot, the desk (tabs, windows, Workspace text), file-out into the checkout, the leave menu — all under ~/.lol/.
inspector-history.orgWhat inspectors did on Interlisp-D, the Lisp Machines, Smalltalk, CLIM and SLIME, and the four powers built here: all instances, why an object is alive, eval in its context, settable frame locals.
agent.orgAn LLM client native to the image: JSON/SSE and the Messages protocol in Lisp, the introspection layer as its tools, gated writes as a condition with restarts, C-c C-a Ask it.
terminal.orgThe terminal pane (SuperL-↵): pseudo-terminals, sessions and controlling terminals, escape sequences and Williams’ parser, the cell grid, keys as bytes, mouse and bracketed paste.
web-browser.orgThe web browser (SuperL-b): the host’s Chrome, headless in a container, driven over the DevTools protocol; screencast frames drawn by the Lisp, our input sent back. Why Chrome over WPE.
file-manager.orgThe file manager (Super-f): folders and files as subjects, the operations, safe save, the Spotter’s path grammar. Previews: previews.org.
containers.orgRunning a full distro’s projects (a web app with a database) without growing the image: a user-namespace container over the host’s Debian, per-directory overlays, you inside as yourself.
processes.orgConcurrent components sharing the screen: one writer of /dev/fb0, sending a view vs sending pixels, workers in a second process, the sandboxed Accept, the sb-posix audit.
clipboard.orgThe clipboard as plain data: history, the Emacs kill ring, PRIMARY vs CLIPBOARD, rectangles, undo.
org.orgOrg files in the environment: colouring, folding, heading motion, subtree edits, links, the outline as a subject.
screencast.orgScreencasts with sound: the HDA kernel options, a pure-Lisp ALSA mixer, the recorder (live or a damage log), playback through the host’s MPlayer.
fonts.orgHow a character becomes pixels: a TrueType outline rasterised in pure Lisp, or the Cozette bitmap fallback, and how the size changes at run time (SuperL- / - / 0=).
diagnostics.orgWhy a frozen screen happens and what the machine writes down about it: the session log, stall reports, the kernel log, crash-then-reboot. How to read it from the host.

The machine underneath

FileWhat it covers
micro-distro.orgThe EFISTUB boot chain, USB creation, real-hardware boot, the host’s GRUB entry.
sbcl-init.orgSBCL as PID 1: the preinit shim, the supervisor, the build, updating from inside.
kernel-config.orgEvery kernel option we enable and why (single source of truth).
framebuffer.orgFramebuffer → efifb → fbcon, /dev/fb0, drawing images. Why there is no GPU driver.
input.orgInput devices: evdev, finding devices without udev, poll(2), the wheel, every keyboard and pointer at once, hotplug, keyboard layouts.
storage.orgThe host’s disk: NVMe + ext4, found by reading superblocks, mounted read-only but for /home; PID 1 drops to the user with five capabilities, lol-rootd keeps root for a few jobs.
networking.orgThe network layer in Lisp: DHCP, routes, DNS, SNTP, HTTP/1.1 and HTTPS (the host’s OpenSSL, loaded at run time), IPv6, Wi-Fi through the host’s wpa_supplicant, the TCP REPL.
systray.orgThe systray’s data: battery from sysfs, time from the RTC, the network item.
line-editing.orgReadline-class REPL editing in pure Lisp.
x11.orgThe pure-Lisp X11 client (no Xlib): why “supporting X” is just a socket protocol, and how the browser gets a window on the dev host.

Background and inspiration

FileWhat it covers
steps.orgInspiration. VPRI’s STEPS and Piumarta & Warth’s Open, Extensible Object Models (2008): the paper summarised, what LoL shares and doesn’t, and the loc.sh split of our code into ours vs conformance.
learn-clos.orgFrom-scratch tutorial: CLOS (multiple dispatch, method combination) and the MOP — the Lisp the code browser is built out of.
learn-networking.orgFrom-scratch networking tutorial (progress tracker + code links).
background.orgBackground theory: UEFI handoff, x86 modes, USB-HID, multicore, entropy.
AGENTS.mdWorking notes and conventions for AI agents in this repo.

Layout

build.sh                 one-step build (userland, --kernel, --run, --interactive, --install-host)
deps.sh                  fetch/link/update the ./linux and ./sbcl trees
check-links.sh           verify every [[file:...]] link in the .org docs resolves
check-*.lisp             boot the image under QEMU and assert behaviour over QMP + the net REPL
refresh-screenshot.sh    re-capture the screenshots (headless QEMU, driven over QMP)
loc.sh                   lines of code/prose, by language and by origin (ours vs conformance)
kernel/                  pinned .config snapshots (config-<version>)
initramfs/               preinit.c, lol-ct.c, the Lisp modules (*.lisp), the cpio list, alien assets
poc/                     the pixel toolkit and the shell — canvas, text view, morphs, X11
                         client, the Cozette font blob — plus host tests. Host-runnable
                         from a plain sbcl, AND baked into the image (build.sh loads it in place)
media/                   screenshots (archived per date) + the HTML design mock-ups
host-client/             HOST-side tools (NOT in the image): the net-REPL client, QMP, PNG, mocks
iso_root/                build output: BOOTX64.EFI + initramfs.cpio (gitignored)
README.org               this file (the only .org in the root)
doc/                     all other documentation (*.org); doc/background/ = theory + tutorials
linux -> …  sbcl -> …    gitignored symlinks to the external source trees
sources/                 (optional) where deps.sh downloads trees (gitignored)

Licensing

This project’s own code — preinit.c, the Lisp modules, build.sh, deps.sh, the .org docs, and the kernel/config-* snapshots — is released under the MIT License (see LICENSE).

Why MIT and not GPL. This repository does not redistribute the Linux kernel (its source and the compiled bzImage are gitignored; deps.sh fetches the tree), and our userland talks to the kernel only through system calls, which the kernel’s own licence explicitly excludes from being a derivative work. So our code is ours to license.

Third-party components you obtain or build separately keep their own licences:

ComponentLicenseHow it reaches you
Linux kernelGPLv2fetched by deps.sh from kernel.org; never redistributed here
musl libcMITstatically linked into preinit (you build it)
SBCLpublic domain + BSD-stylethe runtime your image embeds (you build it)
GNU C Library (glibc)LGPL-2.1-or-latercopied verbatim into the initramfs — the SBCL binary is dynamically linked, so ld-linux-x86-64.so.2, libc.so.6 and libm.so.6 are taken from your host and shipped (see initramfs/initramfs.sbcl.list)
Intel Wi-Fi firmware (iwlwifi-*.ucode)Intel’s binary-redistribution licence (LICENCE.iwlwifi_firmware in linux-firmware; Debian’s copyright file calls it binary-redist-Intel)copied by build.sh from your host’s /lib/firmware (Debian’s firmware-iwlwifi) into the initramfs only; never committed here; card-keyed, LOL_WIFI_FIRMWARE=0 leaves it out (networking.org, Wi-Fi)
regulatory.db (+ .p7s)ISC (wireless-regdb)likewise copied from your host’s /lib/firmware (the upstream-signed regulatory.db-upstream), never committed
OpenSSL 3, wpa_supplicantApache-2.0; BSD-3-Clausenot shipped at all: the image loads/runs the host’s own copies from /mnt/host at runtime (networking.org, Userland half — reaching the network from SBCL, Wi-Fi)
stb_imageMIT or public domain (Unlicense), your choicecommitted here, vendored as poc/vendor/stb_image.h; compiled into libstbi.so, which ships in the image for JPEG/PSD/HDR previews (previews.org)
Cozette (font)MITcommitted here as poc/cozette.lolf (our 6×15 blob, regenerated from the upstream BDF) with the upstream license beside it in poc/cozette-LICENSE.txt; it also ships inside the image, as the fallback font
DejaVu Sans Mono (font)Bitstream Vera licence (DejaVu’s own changes: public domain)never committed: build.sh copies it from the build host (Debian’s fonts-dejavu-core, /usr/share/fonts/truetype/dejavu/) into the image at /usr/share/lol/mono.ttf. The licence permits redistribution with its notice (/usr/share/doc/fonts-dejavu-core/copyright on the host). LOL_FONT ships another file instead — then that file’s licence applies

If you distribute a bootable image or USB, three obligations come along; none affects your own MIT code:

  • The kernel (GPLv2). The image contains the compiled bzImage. Make the corresponding kernel source available (unmodified upstream linux-7.2.5 from kernel.org) together with the exact .config, which kernel/ already keeps.
  • glibc (LGPL-2.1+). The image carries the glibc loader and libc/libm as unmodified binaries. Say which version you shipped, pass its licence text along and make its source obtainable. The relinking requirement is met because SBCL is dynamically linked and the .so files are ordinary replaceable files in the initramfs.
  • Wi-Fi firmware. If the image carries the Intel firmware (the default when the build host has it), Intel’s licence permits binary redistribution on its own terms: read LICENCE.iwlwifi_firmware (Debian: /usr/share/doc/firmware-iwlwifi/copyright) and pass it along, or build with LOL_WIFI_FIRMWARE=0.

Everything else is aggregation: your MIT userland sits alongside these on the medium, unaffected. (A plain-English summary of what the licences cover, not legal advice — read them if you intend to ship.)

Artwork

The alien sprite (initramfs/alien256.png and the derived initramfs/alien.rgba) is the Lisp alien logo by Conrad Barski, M.D. — https://www.lisperati.com/logo.html — released into the public domain (“anyone may use these freely for any purpose and in any way”). Attribution isn’t required but is appreciated, so: thanks, Conrad. The logo is also the namesake nod behind “LoL” / Land of Lisp.

About

A Lisp Machine–style environment on a bare Linux kernel: SBCL is PID 1 and the whole userland. A pixel-native, Smalltalk-inspired live environment on the framebuffer that browses, inspects, debugs and recompiles its own source. Includes a terminal, web browser, containers, networking and an LLM agent, all in Lisp.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages