ARM64 · Linux kernel · BEAM as PID 1

An operating system whose userland is written in Elixir.

Lepton boots on Apple Silicon virtual machines and runs everything you touch — init, the shell, a Spacemacs-style editor, a tmux-compatible multiplexer, git, a GitHub CLI and a package manager — as Erlang processes. It configures itself from your dotfiles.

28,174lines of Elixir in the OS
125commands
140self-tests, run inside the OS
~0.1 sfrom PID 1 to userland
120 MiBbootable hybrid ISO

Everything above the kernel is Elixir

Each program is a BEAM process with a Unix-style PID, connected by pipes that are Erlang I/O servers.

lsh — the shell

Pipes, redirection, globbing, $(…), if/for/while, job control with C-z/fg, oh-my-zsh style emacs line editing, autosuggestions, syntax highlighting and a starship-compatible prompt.

le — a Spacemacs-style editor

Evil operators, motions and text objects, the SPC leader with which-key, helm-style pickers, splits, ex commands, Monokai, relative line numbers and a magit-style git screen.

tmux, in Elixir

Sessions that survive detach, splits, layouts, resize, zoom, vi copy mode and a themepack status line — all driven by your real ~/.tmux.conf, including if-shell.

git and GitHub

Format-compatible git (objects, packs, index v2) with clone, fetch, pull and push over HTTPS or SSH — ssh-keygen, gh ssh-key add, and your private repos are a git clone git@github.com: away. A gh CLI for repos, issues and PRs. Your gitconfig aliases just work.

lpm — packages from hex.pm

Resolves dependencies, verifies checksums and compiles Elixir and Erlang packages inside the OS. Packages can ship new shell commands, but they can't take over built-in ones. Built-in apps update only through a signed list of official updates, published by the lepton organization on hex.pm: lpm upgrade grep, and lpm revert grep to go back.

An installer that writes disks

lepton-install writes a GPT, a FAT16 EFI partition and an ext2 data partition — all in Elixir — so your home directory persists across reboots.

Networking without C

Links, addresses and routes are configured over rtnetlink through :socket; a DHCP client runs at boot. ping, curl, ip and a text browser, www.

Tested from the inside

lepton-test runs the same ExUnit suite inside the booted OS that runs on a laptop — mounts, drivers, DHCP, even cloning a repo from GitHub.

Behaves like a real machine

PID 1 mounts filesystems, loads kernel modules from modules.dep and logs in every console. svc (also systemctl) runs long-running apps like systemd does: unit files, restart on failure, start at boot, svc logs -f. Services stop cleanly when the virtual power button is pressed.

Configured by your dotfiles — not a copy of them

The build installs a dotfiles repo into /root. Each program then reads its native config file at boot. keys shows exactly what was loaded.

# Use ctrl-t instead of ctrl-b
unbind C-b
set -g prefix C-t
set-window-option -g mode-keys vi
bind v split-window -h
bind s split-window -v
bind h select-pane -L
bind-key -r H resize-pane -L 5
bind + new-window -d -n tmux-zoom 'clear && echo TMUX ZOOM && read' \; swap-pane -s tmux-zoom.0 \; select-window -t tmux-zoom
if-shell "uname | grep -q Linux" "source-file ~/.tmux.linux.conf"
  • Prefix C-t, every bind/unbind, -r repeat tables
  • \; command chains — the zoom trick works as written
  • if-shell runs its test in lsh, so the Linux branch is taken
  • vi copy mode with v / y / Y → xclip
  • @themepack powerline/default/cyan colours the status line

How it fits together

Lepton is honest about its foundations: a stock Linux kernel and the Erlang runtime sit below; everything that defines behaviour is Elixir.

Elixir userland lsh · coreutils · le · tmux · git · gh · ssh · lpm · www · installer TTYs & line discipline · VT emulator · netlink + DHCP · init
Erlang/OTP 29ERTS, kernel, stdlib, ssl, crypto, inets
Linux 6.18Alpine virt kernel · glibc · GRUB (UEFI)
ARM64 VMUTM · QEMU · Apple Silicon
  1. UEFI finds the El Torito image on the CD — or the GPT partition on the hybrid ISO when attached as a disk.
  2. GRUB loads the kernel and initramfs; both were packaged by Lepton's own Elixir cpio, FAT and ISO 9660 writers.
  3. Linux executes ERTS directly as /init; the kernel command line carries the runtime's flags.
  4. Lepton.Init (PID 1) mounts /proc, /sys, /dev, loads drivers and mounts the persistent disk.
  5. Sessions open on the display and serial consoles, each a TTY process running lsh, configured from your dotfiles.
What isn't Elixir, and why
LayerSourceWhy
Linux kernel + modulesAlpine linux-ltsThe BEAM needs a kernel.
wpa_supplicantAlpineWPA authentication for Wi-Fi; Lepton drives it over its control socket.
ERTS / OTP 29Hex.pm prebuiltThe runtime itself.
glibc & librariesUbuntu 24.04ERTS links against them.
GRUB (EFI)DebianFirmware-to-kernel loader.
busybox (static)AlpineA syscall shim for exactly mount, finit_module and termios ioctls, which ERTS cannot issue. Never exposed as a command.

Screens from the running system

Captured from Lepton's display console under QEMU, on the same virtual hardware UTM uses. Click to enlarge.

Download Lepton

A ready-to-boot UEFI image for ARM64, for UTM and QEMU on Apple Silicon. It is a hybrid image: it boots when attached as a CD or as a disk.

File
lepton.iso · 120 MiB
Architecture
aarch64 (ARM64), UEFI
Contents
Linux 6.18 · Erlang/OTP 29.1.2 · Elixir 1.20.5
SHA-256
a9cd5cc5e5cbde87d4705f04030496d59bf0d3962075ce68a03bc936b880753e
curl -LO https://github.com/danieljaouen/lepton.iso/releases/latest/download/lepton.iso
shasum -a 256 lepton.iso   # compare with the SHA-256 above

Get started

1 Get the ISO

Download it, or build your own (with your dotfiles) on Elixir/OTP 29:

git clone --recursive https://github.com/danieljaouen/lepton
cd lepton
mix lepton.iso          # -> out/lepton.iso

2 Boot it

In UTM: Virtualize → Linux → choose lepton.iso. Add a serial device to get a second console. Or use QEMU:

mix lepton.qemu         # window, like UTM
mix lepton.qemu --test  # headless: boot and run the self-tests

3 Install and explore

Add a VirtIO drive, then inside Lepton:

lepton-install          # GPT + EFI + ext2, all in Elixir
lepton-tutorial         # an 11-lesson tour
lpm install jason       # packages from hex.pm
lpm official            # signed updates for built-in apps
svc start httpd         # services, like systemctl
keys                    # bindings loaded from your dotfiles

Roadmap

Done

A complete CLI system

Shell, editor, multiplexer, git & GitHub, packages, services, installer, networking, graceful shutdown.

Done

Wi-Fi

wifi scan and wifi connect join WPA2 networks through USB adapters, with drivers loaded as soon as one is plugged in.

Later

A real browser

www already fetches and lays out HTML as text. CSS, box layout and rendering to the compositor come next.

Credits

Lepton OS was designed and written by Claude (Anthropic's Claude Opus 5.5, an AI model), working in Claude Code at the direction of Daniel Jaouen, whose dotfiles define how it behaves.

It stands on the shoulders of Linux, Erlang/OTP, Elixir, Alpine Linux, Debian, Ubuntu and Hex.pm. Official app updates are maintained by the lepton organization on hex.pm.