Install, update, and uninstall

Nix

Nix is the simplest way to install Autolith:

nix run github:luciusmagn/autolith

The first launch builds Lisp images Autolith needs to launch. These images live under ${XDG_DATA_HOME:-~/.local/share}/autolith/nix/images/}.

Linux binary release

It is possible to install autolith on Linux x86₆₄ via a shell installer:

curl -fsSL https://sh.lambda-symbolics.com/autolith | sh

The installer verifies the release archive's SHA-256 before extraction. The checksum must identify that exact archive; malformed or missing checksums abort installation. The initial shell script is fetched over HTTPS.

Read the installer before piping it to a shell, or use Nix if that tradeoff is unwelcome. Linux binary releases require OpenSSL and Bubblewrap. Bubblewrap provides the filesystem and network isolation used for sandboxed command execution. The installer names the missing dependency instead of installing a release that cannot offer sandboxed or safe automatic execution. The launcher uses the installation layout, rather than an environment marker alone, to distinguish binary, Nix, and source starts.

Autolith automatically checks for updates at most once every 20 hours. To install the latest binary release and exit without starting a session:

autolith update

The command exits successfully when updated or already current, and returns a nonzero status if checking or installing fails. autolith --update is an equivalent update-and-exit alias. Run autolith afterward to start the new release. Both spellings accept --help or -h; extra arguments exit with status 64 before checking for updates. Use your flake or Nix profile to update Nix installations; update the checkout and run ./script/bootstrap for source installations. These installations explain their update mechanism without building or starting Lisp images.

To update from a session and restart it with its original command arguments:

(update)

Release archives are built and checked by the installer host. GitHub publishes release metadata after the host checksum is available. See Release service.

Source checkout

For a fresh macOS machine:

brew install sbcl rust cmake pkg-config openssl@3
curl -o /tmp/quicklisp.lisp https://beta.quicklisp.org/quicklisp.lisp
sbcl --no-sysinit --no-userinit --load /tmp/quicklisp.lisp \
  --eval '(quicklisp-quickstart:install)' --quit

On Linux, also install Bubblewrap with your distribution's package manager. Autolith uses its bwrap executable to isolate the host filesystem and network for sandboxed commands and the sandboxed decisions made by automatic permission mode. Nix installations include it. Bubblewrap is not a macOS or BSD dependency. Without platform sandbox support, the sandbox choice is unavailable; explicit once, always, and full approvals run with the user's full privileges.

With Quicklisp in ~/quicklisp, bootstrap and check the checkout:

./script/bootstrap
./script/check

The check runs FiveAM tests in isolated SBCL processes, defaulting to the available logical CPU count (one worker if detection fails), and verifies the pristine recovery image. Each run first saves an active image of the checked source, so cases that start a fresh Autolith boot that core instead of loading the system. List or select test suites and individual cases with:

./script/check --list
./script/check --suite workspace-resource --suite fixtures
./script/check --test test-workspace-file-resources --jobs 1
./script/check --jobs 8 --timeout 900

Selected runs skip recovery probes. Selectors are exact, case-insensitive names and can be repeated; unknown names fail. --jobs controls process concurrency, and --timeout sets the deadline per worker in seconds (default 600). Results include per-case timings and the slowest cases. AGENTS.md documents test registration, reusable fixtures, and interactive Lisp entry points.

To put a checkout into PATH:

mkdir -p ~/.local/bin
ln -sfn "$PWD/bin/autolith" ~/.local/bin/autolith

This is assuming you have .local/bin/ in PATH.

Windows

For the Windows x86-64 development artifact, extract the archive into a writable folder and run .\bin\autolith.cmd from PowerShell. Use Windows 10 version 1903 or newer. The bundled SBCL executable has a UTF-8 process manifest for Unicode paths; system-wide locale changes and 8.3 filenames are unnecessary. The first launch builds per-user cores under .autolith-images beside the release.

To build the source checkout, install Git for Windows, Rust with the MSVC toolchain and Cargo, and Quicklisp under %USERPROFILE%\quicklisp. Put clang on PATH for the ColorLisp syntax library. An SBCL 2.6.6 or newer on PATH is used when present; otherwise the bootstrap downloads the official SBCL Windows binary pinned in sbcl-windows-releases.sha256, verifies its SHA-256, and unpacks it below the data root without registering it with Windows. OpenSSL 3 comes from Git for Windows, from AUTOLITH_OPENSSL_DIRECTORY, or from a native\openssl directory beside the sources.

From PowerShell, bootstrap and check the checkout:

script\bootstrap.ps1
script\check.ps1

script\check.ps1 takes the same selectors as ./script/check. Checks that need FIFOs, forked children, pseudo-terminals, POSIX file modes, or the POSIX shell are recorded as skipped. To package a Windows archive, install the Windows SDK (including mt.exe) and run script\package-windows-release.ps1 -Tag VERSION. The POSIX release-server scripts are not built on Windows.

Start a session with bin\autolith.cmd or bin\autolith.ps1; both take the arguments bin/autolith takes. Windows Terminal is the primary console; legacy consoles without virtual-terminal input are refused with a message.

Windows sandboxed commands use the bundled AppContainer helper. They can write in the workspace and a private temporary directory, read system applications and explicit tool directories, and have no network access. Repository metadata is protected. Bootstrap builds the helper with Clang; release archives include it.

Windows supports supervised detached sessions, client-first starts, and exact-heap restart checkpoints. It withholds fork-based checkpoint saving and the unix management REPL transport.

Uninstall

To remove Autolith and keep your data:

autolith uninstall

The launcher lists what it will remove, asks for confirmation, and exits without starting a session; --yes skips the prompt, which is required when no terminal is attached. It removes the packaged installation and its command link, managed SBCL runtimes, the active and recovery images, retained generation cores, saved worker images, Nix image trees, release markers, crash capsules, launcher pointers, session sockets and leases, provider caches, and the cache root.

User data stays in place: conversations, inference traces, memories, papercuts, agendas, plans, pending input, private image commits, the mutation journal and mutation history, permissions, preferences, credentials, and the configuration root. Stop running sessions first. A source checkout stays as well; delete it yourself. Nix installations also need the package removed from the flake or profile. On Windows the launcher prints the folders to delete, because the runtime in use lives inside them.