ChrysaLisp: a self-hosting parallel operating system for programmers

ChrysaLisp's distributed systems model

ChrysaLisp addresses a specific problem: it puts a complete operating system, programming environment, and distributed execution model into one self-hosting codebase. It is aimed at programmers who want to inspect how an operating system can be built around parallel and distributed execution rather than assembled from a general-purpose kernel, userland, compiler collection, and package ecosystem. The intended audience is therefore narrower than the set of developers who might install Linux or macOS.

The architecture is described as 64-bit and MIMD. Machines discover one another through mesh networking and join one system when they hold the same key. Link endpoints prove possession of that key before carrying traffic. This design puts identity and participation ahead of conventional host configuration, although the README does not document the operational process for rotating keys, recovering from a compromised node, or integrating an unrelated network.

The README calls the distributed object store a new feature that remains in development. Its objects are divided into blocks named by SHA-256. Machines agree on block placement through a shared hash calculation, retain several copies, compare their records, and copy missing data. The `(storage-stream path)` interface exposes an object as an ordinary seekable stream while later blocks are still arriving. A program called a gopher can travel to the relevant blocks and return an answer. This is an interesting execution model, but the project labels the subsystem as in development, so production storage expectations would need direct examination of `docs/ai_digest/storage_service.md`.

VP64 portability and the self-hosting build

The Virtual Processor, or VP, is the main portability boundary. The README describes VP as a 64-bit, RISC-like target implemented for x64, ARM64, RISC-V64, and LA64. ChrysaLisp also includes a VP64 emulator for unsupported platforms and bootstrapping. The build Makefile reflects this mapping by deriving build identifiers from `uname`: x86_64 becomes `AMD64`, riscv64 becomes `RISCV64`, and other 64-bit systems are mapped to architecture-specific values including `ARM64` and `LA64`.

Self-hosting means the repository includes its own assembler, Lisp interpreter, and build tools. The system is not presented as a collection of native utilities operating on a conventional host OS. Instead, much of its development environment exists inside the system being built. The Makefile selects separate object directories for GUI and terminal builds, while GUI selection checks for SDL3 through `pkg-config` and can fall back to SDL2.

That architecture reduces dependence on the host CPU instruction set, but it does not remove host requirements. The GUI still needs a supported graphics backend, and the operating systems listed in the README have separate launcher scripts such as `run.sh`, `run.ps1`, and `run.bat`. For Raspberry Pi, the README identifies special 64-bit framebuffer support. A prospective adopter must therefore verify both virtual-target portability and the quality of the host-specific launcher, graphics, input, and networking path. The repository layout suggests broad platform work, but it does not turn VP64 into a claim that every application or host dependency is portable.

Clone, dependencies, and first ChrysaLisp launch

The README recommends downloading `ChrysaLisp-snapshot.zip` from the ChrysaLisp Releases page for the quickest route because the archive contains source and a pre-built VP64 boot image. Developers who prefer the default `master` branch can clone the repository with the documented command:

git clone https://github.com/vygr/ChrysaLisp.git
cd ChrysaLisp

On Debian or Ubuntu, the documented build dependencies are installed with:

sudo apt-get install build-essential git pkg-config

If the platform provides SDL3 development files, the README gives this installation command:

sudo apt-get install libsdl3-dev

The project says that `make install` uses SDL3 when available and otherwise uses SDL2. GPU shader drawing requires SDL 3.4 or later, so the presence of a package named `libsdl3-dev` does not by itself confirm the required feature version. On macOS, the README also lists Xcode Command Line Tools and `brew install sdl3`.

After dependencies are present, `make install` is the documented installation command. The README does not provide a complete post-install launch sequence. The repository contains `run.sh`, `run.ps1`, and `run.bat`, but the Quick Start Guide does not state their full invocation or expected arguments. Start with `docs/intro.md`, which the README identifies as the detailed installation, build, and launch walkthrough, and confirm the platform-specific launcher before attempting the first graphical session.

Terminal, Lisp, assembler, and shader paths

ChrysaLisp provides several ways to write and execute code. Its Lisp interpreter handles scripting, development, and system tasks. The object-oriented assembler supports the class system used from low-level assembly through higher-level Lisp code. Functions can be loaded and linked on demand, which the project presents as dynamic binding and a way to share code among tasks. These features make the environment internally coherent, but they also mean that existing Common Lisp habits may not map cleanly to ChrysaLisp's particular implementation and system model.

The `vpx` compiler accepts C-like expressions and compiles them into VP code from Lisp. A conventional compiler workflow cannot simply be transferred unchanged because VP is ChrysaLisp's own target rather than the host CPU's native instruction set. Developers interested in native code generation need to inspect the compiler and class library interfaces rather than assume that C source is accepted directly.

The shader system is unusually broad. Shaders are written as s-expressions and type checked in Lisp. According to the README, the same source can produce GLSL, Metal, SPIR-V for Vulkan, native VP code for CPU execution, and a Lisp lambda used as a checked reference. The SDL3 host can draw shaders through Metal on a Mac or Vulkan on a Raspberry Pi. Without a GPU, participating network nodes can divide an image into tiles and draw them in parallel. A canvas may hold pixels in shared memory, while Whiteboard stores board content as a `.cwb` text file rather than pixels.

This approach is useful for controlled graphics experiments, especially because one shader has several explicit targets. It is the wrong abstraction when a project already depends on an established graphics API, mature asset pipeline, or driver ecosystem and cannot accept a custom shader representation.

Mesh, sync, rack, and test-based verification

ChrysaLisp's system tools act across linked machines rather than relying on `ssh` or `rsync`. The `sync` command compares tree hashes and transfers only differing files, making another machine's files match the local tree. The README gives this multi-machine execution example:

rack "tests -a"

The documented behavior is to bring every machine to the same level and run the command on each node. The `mesh` command reports participating machines. These are project-specific abstractions, not wrappers named after familiar Unix commands with identical operational semantics. Adoption therefore requires checking how nodes are authenticated, how link failures are reported, and what happens when machines are at incompatible versions.

Testing follows a dependency-oriented cache model. The README says the repository contains more than 6,000 assertions across 140 modules and that `tests` selects modules standing on what changed. The demonstration section also names `make test`. These are separate documented entry points, but the README does not explain the distinction. A change-specific test cache can reduce unnecessary execution, yet it also makes correct invalidation important: a test selected according to source dependencies must detect whether its prerequisites changed.

Static checks include `check`, `lint`, `forward`, `imports`, and `includes`. According to the README, these commands inspect source and report faults visible from text before execution. They complement the dynamic test system, but they do not replace runtime verification across the available CPU architectures, GUI drivers, storage topology, or network links.

License, maintenance, and adoption boundaries

The repository is licensed under `GPL-2.0`, and the top-level files also include `LICENSE-EXCEPTION`. Any adoption decision must account for both files rather than relying only on the license label. The README does not explain the scope of the exception, so it does not support conclusions about redistribution or linking obligations. That is a legal question rather than an engineering one, and organizations using ChrysaLisp should review both files with their own counsel.

The repository is not archived, and its last push was on 2026-10-17. Recent releases include v6.0 Batholith on 2026-09-10, v6.1 Confluence on 2026-09-18, and v7.0 Pipsqueak on 2026-10-05. These dates indicate recent project output, but they also make upgrades a concrete issue for an operating-system codebase. The README does not define a stable release policy, compatibility promise, migration guide, or rollback procedure. An adopter should compare the release documentation directly and preserve a known bootable snapshot before changing versions.

The clearest audience is a developer studying self-hosting, VP-level portability, distributed object storage, or custom GUI composition. It is a poor fit for routine server administration, dependency-heavy application delivery, or environments that require mainstream vendor support. The storage subsystem's development status, host-specific GUI requirements, and absence of documented rollback instructions are concrete reasons to begin with a disposable host and a specific architecture target.

Editorial conclusion

Developers should consider ChrysaLisp when the main goal is to study or modify a complete parallel operating system rather than run ordinary applications on a general-purpose host. Projects that depend on mature Linux packages, conventional drivers, or established deployment practices should stay with that model. Before adoption, verify that `make install` completes for the intended architecture and GUI driver, confirm that the required SDL version is available, and read `docs/intro.md` for the platform-specific launch sequence.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. vygr/ChrysaLisp on GitHub