.lexe

One file. Double-click it. It installs, sandboxed, with no root and no repository.

What you see before anything is installed: who signed it, what it may do, and what the sandbox will enforce.

A .lexe file is one signed, self-describing application. That part is not new.

This part is: the payload inside it does not have to be a Linux binary.

All three are implemented, and all three are demonstrated end to end by tests you can run. A Windows GUI program really opens a window on Linux — through Wine and through Proton — and tests/acceptance/09_windows_gui.sh proves it with xwininfo rather than with the runtime's own opinion of itself.

./scripts/test.sh --all      # every lane. PASS / FAIL / SKIP / BLOCKED.

# Build it
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j"$(nproc)"

# Make a package out of an example, and look at it before trusting it
./build/lexe keygen key.json
./build/lexe build examples/native/cli-hello -o hello.lexe --key key.json
./build/lexe inspect hello.lexe          # identity, signature, permissions, checks

# Install and run it
./build/lexe install hello.lexe
./build/lexe run org.lexe.examples.cli-tool -- 2 9 16

lexe inspect is the interesting one. It runs the whole verification pipeline and tells you what each stage concluded, before anything is written anywhere.

docs/HANDOFF.md is the running record of what is proven and what is next.

Two commands, and the difference is the point:

lexe uninstall com.example.app   # remove the program; keep what makes a reinstall a return
lexe purge com.example.app       # make .LEXE forget the application entirely

After purge, installing the app again is a first install: you are shown the publisher key as "first seen", and nothing it was granted before carries over. Purge only ever removes what .LEXE itself keeps for that application — files the app wrote anywhere else in your home folder (documents, exports, projects) are yours, and are never touched. Trust is per application: purging one app never changes your decisions about another, even one signed by the same key. The full contract is in docs/REFERENCE-POLICY.md, "Uninstall and purge". (lexe remove is retired; it names both replacements.)

This repository is built around a rule: if it says something works, there is a test that demonstrates it.

./scripts/test.sh --list

Four outcomes, not two. SKIP means "deliberately not applicable here". BLOCKED means "this applies, it is expected to work, and this machine cannot show it" — and a blocked lane is never counted as a pass. What this machine cannot prove, and what would settle each one, is written down in docs/TESTING.md §6.

The most load-bearing example: the portable type's central claim is that the same signed package compiles natively on x86_64 and on AArch64. It is implemented and tested on x86-64. On the physical AArch64 worker the same signed package arrives byte-identical and verifies, and then compilation is refused: that worker has no user namespaces, and .LEXE never builds outside its sandbox. The claim is not demonstrated on AArch64 yet. So that is what the docs say. Emulation is explicitly not accepted as a substitute.

                      lexe
                canonical engine
               /       |        \
            CLI    lexe-ui    lexe-builder

One engine. src/lexe/ is the entire implementation — eleven layered subsystems with a one-way dependency direction, enforced by tests/test_architecture.cpp reading the source tree rather than by a paragraph asking nicely.

Three frontends, and none of them reimplements anything. The CLI is the engine's own entry point. lexe-ui is the consumer frontend and the .lexe file handler. lexe-builder is the developer frontend. When two of them needed the same install-consent logic, the answer was a shared header — not a second copy.

docs/CAPABILITY-MATRIX.md tracks which capability is reachable from where, and what proves it. Its last column is the point: a row with an engine implementation, two frontends and an empty proof cell is a claim, not a capability.

$ lexe help

Applications
  open <artifact.lexe>                     open any .lexe: install a package, launch a run.lexe
  install <file.lexe> [--yes] [--trust]    verify and install a package
  run <id> [--chain <c>] [-- <args...>]    launch an installed application (sandboxed)
  compat <id> [--set <chain> | --auto]     show or change how an application is executed
  apps · list · info · inspect             what is installed, and what a package is
  update · rollback · repair               the rest of the lifecycle
  uninstall <id> · purge <id>              remove the program · make .LEXE forget it
  service [status|enable|disable] <id>     run a service under systemd --user (opt in)
  gc <id> [--keep <n>]                     reclaim old versions (keeps active + n)

Developer
  build <project-dir>                      build a signed .lexe from a project folder
  analyze · sdk verify · pack · keygen     dependencies, portability, low-level packing

Trust & verification
  verify <file.lexe> [--json]              run the verification pipeline
  trust show|classes|block|unblock|forget  inspect signer classes, set local trust

System
  runtime [list | show <id>]               compatibility runtimes this host has, and where
  sandbox                                  the isolation backend and every control it enforces
  doctor [--repair] · integrate            check and repair desktop integration
  errors [<id>]                            structured diagnostics for a failed launch
  config · completion · version · help

Every command has --help with worked examples. --json where a script would want it. Stable exit codes (0 ok, 2 usage, 3 verification, 4 not found, 5 consent, 6 busy, 7 local trust). No ANSI escapes when redirected.

Two commands worth knowing about, because they exist to make the runtime inspectable rather than to do anything:

lexe runtime show proton   # every location searched, in order, and which one won
lexe sandbox               # every isolation control, and its actual state

lexe sandbox reports per-control rather than as one word, because "sandboxed" is not a boolean: a host can have a working backend that cannot establish a network namespace, and saying which is the difference between a security claim and a security fact.

Follows your desktop's light/dark preference, and is switchable in place.	lexe-builder: point it at a folder, fill in a few fields, get a signed package. All three payload kinds.
Drop a package on the window. Dropping is not a shortcut past any check.	Not pictured, because a screenshot would prove nothing: a Windows GUI program running on Linux under the sandbox, with its window witnessed by xwininfo on a display created for the test. That one is tests/acceptance/09_windows_gui.sh, and it runs the whole thing twice — once through Wine, once through Proton.

Only implemented, tested capabilities. The Proof column is what you run.

Kept as prominent as the list above, on purpose.

Not production-ready, and not yet a Developer Preview. The Alpha support contract states exactly what is and is not claimed.

git clone https://github.com/EeshGarg/.lexe.git && cd .lexe
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
sudo ./packaging/install.sh          # or: ./packaging/install.sh --user

packaging/install.sh calls lexe integrate rather than hand-rolling MIME registration, because there is exactly one implementation of desktop registration and this is not it.

Needs: a C++20 compiler, CMake 3.22+, bubblewrap (for isolation — without it the launcher refuses rather than running unconfined), and libgtk-3-dev for the graphical frontends. docs/TESTING.md §4 has the full list and what each package buys you.

Full index and reading order: docs/README.md.

Start here

The specification

Building on it

No dates. docs/ALPHA.md is the current contract.

CONTRIBUTING.md takes you from a fresh clone to a green test run. In short:

./scripts/test.sh --all

One rule worth reading before you open a pull request: a defect is not fixed until a test reproduces it. Understand the root cause, correct it, write a test that fails against the old behaviour, watch it pass against the new one, and confirm the broader suite is still green. A fix without that fourth step is an assertion.

Bug reports, feature requests and portability reports have issue templates. Security findings go privately through the Security tab — SECURITY.md has the channel, the scope, and the documented non-guarantees that are not vulnerabilities.

Proprietary during the pre-release phase, while the signing and trust infrastructure is established — see LICENSE. The stated intent is to relicense under the GPL once that foundation is in place. The specification itself is language-neutral, so conforming third-party runtimes may be implemented independently. Revisions published before the relicense remain under their original Apache-2.0 terms.