A web browser built from the bottom up by AI, using formal verification instead of trust.
- Memory safe: 100% safe Rust except
clazel-sys: 343unsafeblocks (929 lines) that enter the OS sandbox, machine-checked and audited. Of those, 40 are"C-unwind"casts ofobjc_msgSendto a typed function pointer, one per Objective-C message signature that Metal drawing (21) and the macOS window (19) use. Vulkan drawing on Linux adds 55 (51 direct calls and 4 blocks of declarations), and Direct3D 12 drawing and the GPU process's start on Windows add 56, of which 40 are COM method calls through hand-written vtables. Shipped dependencies arelibcand libcrux. - Verified where it matters: the kernel's security policy and every parser of untrusted input carry machine-checked proofs (Verus, Kani).
- Stated, not implied: each crate declares its verification tier, and the trusted computing base is listed in docs/VERIFICATION.md.
Recheck every proof yourself, on Linux x86-64, with:
docker build --platform linux/amd64 -t clazel-verify .
docker run --rm --platform linux/amd64 clazel-verifyEvery crate, where it runs and the full table, with every conformance suite:
docs/STATUS.md. CI redraws both after every push to
main whose full verification passes, so they can lag behind main.
- Browses, in a window.
clazel URLopens a window and draws the page: HTML parsed, style sheets (linked ones included) cascaded, text laid out in the system's fonts, and the result drawn by a sandboxed GPU process, under an address bar that is always the kernel's committed URL. It draws with Metal on macOS, Vulkan on Linux and Direct3D 12 on Windows. - Renders without a window.
clazel --headless OUT URLwrites the page as a PNG, andclazel --text URLis a text-mode browser in the style of Lynx, which is also what runs where there is no window. - Fetches.
clazel fetch URLis acurlclone overhttp:andhttps:, on our own DNS client, HTTP/1.1 parser and TLS 1.3 client, with redirects and cookies. - Not yet: images, forms and JavaScript. Pages in the seven legacy
multi-byte encodings (Shift_JIS, GBK, Big5 and others) are not rendered:
the page says "encoding
<name>is not supported".
What comes next, and in what order, is in docs/ROADMAP.md.
Clazel runs as several processes. The proofs follow the untrusted bytes: the kernel that makes every security decision is proven, and so are the parsers, in whichever process they run. What is not proven (layout, drawing, the window, the I/O shells) is memory safe, sandboxed where it handles page content, and makes no security decisions. The status table gives each crate's tier.
- The kernel (
clazel-kernel) is a proven state machine. Tabs, origins, connections, cookies and storage are its state, and every navigation, request, redirect and cookie is its decision. Its theorems say, among other things, that what a renderer displays is shown for its own tab, under the URL the kernel committed there (theorem_show_only_own_tab,theorem_address_bar_integrity), and that a renderer receives the fetched body whole (theorem_body_is_the_response). - Renderers (
clazel-renderer) parse and lay out pages, one process per origin, inside the OS sandbox: namespaces, seccomp and Landlock on Linux, Seatbelt on macOS, an AppContainer on Windows. The HTML tokenizer, the tree builder and the DOM are proven correct; layout is memory safe and tested, not proven. A renderer talks only to the kernel, over a proven message codec (clazel-ipc). - GPU processes (
clazel-gpu) draw, one per tab, in a sandbox of their own. A renderer sends its GPU process display lists, which are decoded and validated before anything is drawn, and the host shows the pixels in the window (clazel-window) only when the kernel says to paint them. - Parsers of untrusted bytes are ours, in every process, and are proven against a transcription of their standard: URLs, encodings, IDNA, MIME sniffing, HTTP, DNS, cookies, DER and signature checking, HTML and more.
- Shells carry bytes. The host (
clazel), the network shell (clazel-net) and the store's shell (clazel-store-shell) do the I/O and make no protocol decisions: those belong to the proven crates they call. clazel-sysholds everyunsafeblock: single calls into the OS, with no policy of their own.
Each crate declares a tier in its Cargo.toml, and
cargo xtask verify rejects a claim that is not backed:
| Tier | Guarantee | Checked by |
|---|---|---|
| 0 | Memory safe | Safe Rust, Miri, deny-lints |
| 1 | Never panics on any input | Kani harnesses |
| 2 | Functionally correct against an executable spec | Verus proofs |
A proof only shows that code matches its spec. That the spec matches the standard is shown by evidence that machines check too: official test suites (Web Platform Tests, html5lib-tests and others) run through the proven code, differential tests against independent engines, deliberately broken specs that a theorem must reject, and a second, independent transcription proven equivalent to the first. No step depends on a person approving something. The policy, the tools and the trusted computing base are in docs/VERIFICATION.md.
Formalising the standards has found places where they are wrong as written: see docs/ERRATA.md.
scripts/setup.sh # install the pinned, checksummed toolchain (needs rustup)
scripts/verify.sh # every check, fresh proof runs (same as `cargo xtask verify`; CI runs this)
cargo xtask verify --changed # every check, but proofs and tests only for crates changed since origin/main
cargo xtask check # fast static checks onlyThe browser, clazel, and the sandboxed renderer and GPU process it starts
for each tab:
cargo build --release --bin clazel --bin clazel-renderer --bin clazel-gpu # all land in target/release/
target/release/clazel https://news.ycombinator.com/ # open a window on the page
target/release/clazel # or on no page, with the address bar readyIn the window, click the address bar (or press Command-L on macOS, Control-L
elsewhere), type a URL and press Return to go there, click a link to follow
it, and scroll with the wheel, Space, Page Up and Page Down or the Up and
Down arrows. The back button (Command-[) goes back, and Command-R reloads
(Control on Linux and Windows). The kernel fetches every page and
its style sheets, the page is parsed and laid out in a sandboxed renderer,
one per origin, and drawn by a sandboxed GPU process; the address bar is the
kernel's, whatever the page says. A window needs macOS on Apple silicon,
Windows, or Linux with a local X display and the Vulkan loader
(libvulkan-dev to build). On Windows the browser's window and
Direct3D 12 drawing have been run by hand; CI there runs the sandbox and the
host's tests and opens a test window, but never draws with Direct3D 12.
target/release/clazel --headless page.png https://example.com/ # draw one page to a PNG (or a .ppm)
target/release/clazel --text http://info.cern.ch/ # text mode: title, text, numbered links--headless takes --size WxH (1024x768 if not given). --text shows a
page as text, with its links numbered: type a number to follow a link,
g URL to go elsewhere, b to go back, q to quit. It is also what
clazel URL runs where no window can be opened. With a window or
--headless, --gpu=software starts every GPU process on the software
driver (lavapipe on Linux; macOS has none, so nothing is drawn there), and
--gpu=hardware ignores the driver blocklist, with a warning.
target/release/clazel fetch http://example.com/ # GET, redirects followed, response printedfetch resolves the host with our own DNS client and drives the proven fetch
client: it builds each request, frames each response with the proven HTTP/1.1
parser, follows redirects and keeps the cookies they set for the rest of the
run. It needs the Internet. An https:// URL goes over our TLS 1.3 client
with Mozilla's roots as the trust store.
Each GitHub release has a Linux x86-64 tarball with both binaries and an
installer: unpack it and run sudo ./install.sh (or PREFIX=... ./install.sh).
On Ubuntu 23.10 and later, which restrict unprivileged user namespaces, the
installer also adds an AppArmor profile that lets clazel-renderer create the
one its sandbox needs, and nothing else; without it the renderer refuses to
start, by design. Built from source, run the same script once:
sudo packaging/apparmor/allow-userns.sh clazel-renderer "$PWD/target/release/clazel-renderer"The code is written by AI agents under rules (CLAUDE.md) designed so that nobody has to trust them. That leaves a lot of useful work for people, and much of it is work only a person can do.
- Check our work. Rerun every proof on your own machine with the Docker
command above, or
scripts/verify.sh. If anything does not match the verification status table, open an issue: a claim nobody can reproduce is a bug. - Review a spec against its standard. Each
spec.rstranscribes a standard step by step, with its modelling choices listed at the top (docs/SPEC-STYLE.md). Reviews gate nothing, and only people may record one, so a reviewed file means a person read it. See docs/SPEC-REVIEWS.md for how.contract.rsfiles are the shortest route to what each crate actually promises. - Take errata upstream. Agents never file issues with standards bodies; the entries marked "Reported upstream: not yet" in docs/ERRATA.md are waiting for a person to check them and report them.
- Try to break it. Feed the parsers hostile input, look for a spec bug the
proofs would not catch (each crate's
mutations.jsonlists the known gaps, markedsurvives), or close one of those gaps with a lemma or a Kani harness. - Add test suites. Every Tier 2 crate is tested against official suites
and independent engines (
tests/conformance*.rs). Point us at suites we have not vendored, or at engines worth differential testing against. - Run it on your machine. Build it, browse with it, and open an issue
for what breaks. The sandbox tests run in CI on
ubuntu-24.04, macOS arm64 andwindows-2025only; other Linux distributions and kernels are untested. - Read
clazel-sys. It is the only crate withunsafe. Every change is audited by a second model (docs/SYS-AUDITS.md); a person reading it too is welcome. - Build what is missing. The plan is in docs/ROADMAP.md.
Contributions go through the same machine
checks as everything else, whoever (or whatever) wrote them: read
CLAUDE.md first, and expect
cargo xtask verify --changedand CI's full verification to be the bar.
MIT. See LICENSE.