Lilush: The Next Small Thing

The whole stack for networked software, in one binary under 2MB.

Lilush^[1] has its own async I/O runtime on epoll, its own TLS 1.3 implementation, an HTTP client and server, DNS client/server, an embedded key/value database with full text search, a markdown renderer, and a terminal UI toolkit.

Lilush is self-contained, there is nothing to install alongside it, and nothing to audit outside its sources.

This page is served by RELIW, a web server written in Lilush. The source browser at git.lilush.link is lilgit, a cgit alternative written in Lilush.

Linux only, x86_64 only. LuaJIT with FFI disabled, Lua 5.1 semantics, built against musl. Lilush Shell requires Kitty-compatible terminal. Beta, pre-1.0, core module APIs may still break between minor versions.

Core runtime modules

Everything needed to write and ship a networked tool, in one file:

Filesystem & processes: file operations, process manipulation, pipes, forks.
Async I/O: LEV, a coroutine-based runtime on Linux epoll — sockets, timers, combinators.
Networking: TCP/UDP, a full HTTP(S) client, an HTTP(S)/1.1 server, DNS client, Redis client, WireGuard client.
TLS 1.3: LiTLS — a from-scratch implementation, including the crypto primitives, X.509 handling, Ed25519, hashing and HMAC.
MNEME: embedded key/value database with multiple keyspaces, TTL, sorted sets, BM25 full text search, vector similarity search, and encryption at rest.
Terminal UI: UTF-8 aware terminal I/O, styling via TSS (Terminal Style Sheets), and a widget set for building CLI apps.
Extras: JSON, zlib, and a streaming markdown parser and renderer (CommonMark, GFM, djot).

The shell

Lilush comes with a modular Linux shell (as in Bash, Csh or Fish). Lilush Shell features:

Rich prompts: host, user, directory, git info, python venv.
Completions & navigation: tab completions with scrolling, fast directory navigation and history search in the spirit of McFly and zoxide.
Built-in tools: kat (file viewer + pager with media support), lem editor, netstat, dig, wgcli (WireGuard CLI), and more.
Wiki mode: press F3 to read documentation from a local WIKIDB, offline.
Extensibility: add your own plugins. Style everything with TSS.

The builtins are not wrappers around system tools, they are part of the binary. A machine with lilush on it has a shell, an editor, a pager, a DNS client and a WireGuard CLI, whether or not it has anything else.

Lilush Shell relies on a number of Kitty protocol extensions — keyboard protocol, text sizing, terminal graphics. All features are only guaranteed in Kitty, Ghostty, or terminals that fully implement those extensions.

Get started

# Download the latest release and its signature
curl -fLO "https://lilush.link/releases/latest/lilush"
curl -fLO "https://lilush.link/releases/latest/lilush.sig"

# Verify it against the release signing key
cat > allowed_signers <<'EOF'
vladimir@deviant.guru ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICEWU0xshVgOIyjzQEOKtjG8sU8sWJPh25CP/ISfJRey
EOF
ssh-keygen -Y verify -f allowed_signers -I vladimir@deviant.guru \
  -n file -s lilush.sig < lilush

# Run it
chmod +x lilush
./lilush

Install locally:

install -Dm755 lilush ~/.local/bin/lilush   # make sure ~/.local/bin is in PATH

All releases are signed with my SSH key.

Each release also carries a signed SHA256SUMS. See the README for the full verification procedure and for building from source.

The whole stack for networked software, in one binary under 2MB.

Core runtime modules

The shell

Get started

Packages

Contacts