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.
ARM64 · Linux kernel · BEAM as PID 1
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.
Each program is a BEAM process with a Unix-style PID, connected by pipes that are Erlang I/O servers.
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.
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.
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.
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.
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.
lepton-install writes a GPT, a FAT16 EFI partition and an ext2 data partition — all in Elixir — so your home directory persists across reboots.
Links, addresses and routes are configured over rtnetlink through :socket; a DHCP client runs at boot. ping, curl, ip and a text browser, www.
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.
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.
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"
bind/unbind, -r repeat tables\; command chains — the zoom trick works as writtenif-shell runs its test in lsh, so the Linux branch is takenxclip@themepack powerline/default/cyan colours the status line(define-key evil-normal-state-map (kbd ";") 'evil-ex) (define-key evil-normal-state-map (kbd "C-h") 'evil-window-left) (define-key evil-normal-state-map (kbd ",w") 'delete-trailing-whitespace) (define-key evil-visual-state-map (kbd ",q") 'sort-lines) (define-key evil-insert-state-map (kbd "C-y ,") 'my-tab-command) (setq-default evil-escape-key-sequence "jk" display-line-numbers-type 'relative display-fill-column-indicator-column 101)
define-key, evil-define-key, setq, defaliasalias l='ls -lah' alias gc='git commit -m' alias m="mix" export EDITOR=vim export LSCOLORS=gxfxbEaEBxxEhEhBaDaCaD setopt INTERACTIVE_COMMENTS if [[ "x$OS" == "xOSX" ]] ... else alias open=xdg-open fi
setopt are imported, not executedEDITOR=vim makes vim open Lepton's editorLSCOLORS is honoured by lsgit plugin aliases, overridable by yours[include]
path = .gitconfig.local
[alias]
gl = log -n 10 --color=always --all --graph --topo-order --pretty='format:%h %s %d%n(%cr by %cn)%n'
st = status
ci = commit
co = checkout
df = diff
dc = diff --cached
[core]
pager = cat
--pretty=format: placeholders[include] is followed for machine-local settingscore.excludesfile and http.sslVerify are respected[username] format = "[$user]($style) " show_always = true [hostname] ssh_only = false format = "on [$hostname](bold blue) " [directory] truncation_length = 1 format = "at [$path]($style)[$read_only]($read_only_style) "
[text]($style), $vars, $all> on the Linux console, which lacks ❯Lepton is honest about its foundations: a stock Linux kernel and the Erlang runtime sit below; everything that defines behaviour is Elixir.
/init; the kernel command line carries the runtime's flags./proc, /sys, /dev, loads drivers and mounts the persistent disk.| Layer | Source | Why |
|---|---|---|
| Linux kernel + modules | Alpine linux-lts | The BEAM needs a kernel. |
wpa_supplicant | Alpine | WPA authentication for Wi-Fi; Lepton drives it over its control socket. |
| ERTS / OTP 29 | Hex.pm prebuilt | The runtime itself. |
| glibc & libraries | Ubuntu 24.04 | ERTS links against them. |
| GRUB (EFI) | Debian | Firmware-to-kernel loader. |
| busybox (static) | Alpine | A syscall shim for exactly mount, finit_module and termios ioctls, which ERTS cannot issue. Never exposed as a command. |
Captured from Lepton's display console under QEMU, on the same virtual hardware UTM uses. Click to enlarge.
neofetch on the display consoleleA 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.
lepton.iso · 120 MiBa9cd5cc5e5cbde87d4705f04030496d59bf0d3962075ce68a03bc936b880753ecurl -LO https://github.com/danieljaouen/lepton.iso/releases/latest/download/lepton.iso
shasum -a 256 lepton.iso # compare with the SHA-256 aboveDownload 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.isoIn 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-testsAdd 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 dotfilesShell, editor, multiplexer, git & GitHub, packages, services, installer, networking, graceful shutdown.
wifi scan and wifi connect join WPA2 networks through USB adapters, with drivers loaded as soon as one is plugged in.
Pixels to the framebuffer from Elixir, input from evdev, then a compositor where windows are processes.
www already fetches and lays out HTML as text. CSS, box layout and rendering to the compositor come next.
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.