Intent-native, capability-secure OS prototype
User-space drivers · Typed IPC · Rollbackable storage · Transactional apps · Reboot-safe QEMU demos

Quick Review · Flagship Demos · Architecture · Security Model · Release Process

Dezh OS is a bare-metal operating-system prototype built around one strict rule:

No program, app, service, package, driver, or recovery path starts with ambient authority. Every effect must be backed by an explicit capability, grant, namespace, service route, or transaction.

The current system boots on QEMU RISC-V, validates a boot contract, runs isolated U-mode processes, starts a long-lived user-space virtio-block driver, exercises typed IPC, installs SDK-built .dzp packages onto a real disk image, and validates package update/rollback/recovery across reboot.

Dezh is not production-ready. It is an executable OS prototype prepared for architectural and security-model review.

dezh> services
VirtioBlock state=Running task=0 restarts=0

dezh> ipc-typed-demo
[typed-ipc] PASS: OK=OK, BAD_REQUEST=BAD_REQUEST, TIMEOUT=TIMEOUT, DENIED=DENIED

dezh> app-run lab
Dezh Lab :: installable app system probe
[lab-ui] PASS: scheduler, IPC, installer launch, and UI path cooperated

dezh> cairn-demo
[cairn-demo] rollback one step restores the previous commit
[cairn] DENIED: ns=note requires capability CAIRN_NS_0
[cairn-demo] PASS

Many systems treat files, processes, packages, services, or users as the main security boundary. Dezh is exploring a tighter model:

• Intent-scoped authority: grant the narrow effect, not broad ambient access.
• Effect accountability: important state changes should be inspectable, recoverable, and tied to an explicit actor and route.
• Service-mediated persistence: storage flows through a user-space service, not a hidden kernel block path. (Honest caveat: this buys fault isolation and least privilege of the driver process today; memory safety against a malicious driver that programs the device to DMA anywhere needs an IOMMU, which Dezh does not have yet — see threat model.)
• No silent lifecycle changes: package updates, new capabilities, rollback, remove, and physical cleanup are explicit.

The long-term thesis is:

Dezh is an intent-native, effect-accountable OS prototype.

Unlike seL4, Barrelfish, Fuchsia, or Redox — which make access safe — Dezh makes effect accountable: every action an agent takes is bound to its intent, attributable, and reversible where possible. And because the kernel has no ambient authority by construction, that ledger cannot be bypassed.

The real point of comparison is not another OS but user-space agent isolation — gVisor, Firecracker/microVMs, wasmtime/WASI, seccomp+landlock, containers. They confine resources well and ship today; what none of them do is attribute every effect to its authorizing intent and reverse a whole agent mission on a substrate with no ambient authority underneath to route around. ISA (RISC-V, x86_64) is an implementation backend, not the identity: the same program should mean the same thing on any backend. See strategic direction (D021).

The matrix is deliberately honest: Dezh concedes formal verification to seL4 and IOMMU-enforced DMA to Genode/Fuchsia. What it uniquely holds is the effect / mission / intent / agent row group — the axis this project is about — and package signing here is capability-native: a signature binds the authority a package requests, and a publisher key can only authorize capabilities within its own ceiling (granted = requested ∩ signer_ceiling). Full lineage and per-system detail in Related Work and Novelty; the signing design in Package Signing.

flowchart LR
    A["Actor (agent / task)"] -->|opens| I["Ahd: intent = capability ceiling"]
    I -->|"derive = requested AND ceiling"| D["Derived capability (proven subset of intent)"]
    D -->|acts| E["Sand effect record: actor -> intent -> cap -> reversibility"]
    E -->|grouped by intent| M["Sfar mission"]
    M -->|sfar-plan| F["rollback forecast"]
    M -->|sfar-rollback| R["retract / compensate / refuse"]
    E -->|tbar| P["provenance graph"]
    I -->|"intent-revoke / lease"| X["authority withdrawn, provenance kept"]

• Bare-metal RISC-V boot on QEMU virt in S-mode through OpenSBI.
• x86_64 kernel boots from a GRUB Multiboot2 ISO in QEMU and VirtualBox, with a 32-vector exception IDT (faults reported, not silent triple-faults), and runs the byte-identical .dzp Dezh-IR package.
• Pol (Linux personality): a real, unmodified static Linux/RISC-V ELF runs capability-gated; the same bytes also run on real riscv64 Linux.
• Sv39 U-mode process isolation and contained page faults.
• Capability-gated syscalls for print, time, IPC, device, and block access.
• User-space virtio-block daemon with explicit MMIO and DMA grants.
• Typed IPC v0 with status codes, request ids, timeouts, and counters.
• Boot-managed service registry with stop, restart, and controlled fault demo.
• Reboot-safe package store for SDK-built .dzp apps.
• Transactional package install/remove/update/rollback with journal recovery.
• Package pin/unpin, review, explicit GC, quarantine, and cap-escalation review.
• Cairn v1: an on-disk commit-log store with per-app namespaces. Every commit records its parent ref, object hash, and actor; rollback moves a ref without erasing history and survives reboot.
• Kernel-attested capability checks in services: the kernel records the sender's capabilities on every IPC message, so the storage service enforces namespace access against values a client cannot forge — and denials name the missing capability.
• Agent containment: an SDK-built agent app runs with manifest-scoped grants (its own namespace only), its bad write is undone by a one-step rollback, and a no-capability app is denied by the kernel.
• Embedded demo apps: note, lab, calc, and vault.
• No-grant MMIO proof: a task without device grant faults without killing the console.

One reproducible demo per differentiator (see the roadmap for scope and honest wording rules):

The W8 intent/effect runtime is complete — intent as the only path to authority (Ahd), the unbypassable effect ledger (Sand), honest whole-mission rollback with compensation and multi-namespace authority (Sfar), a five-escape adversary (redteam), and explainable denial + provenance (why-denied / Tbar). See the threat model for what is and is not defended.

One command (overnight) — the whole differentiator. Full captured transcript: docs/demo-transcript-overnight.md.

Dezh is meant to be scrutinised, not just demoed. The scientific lineage and the precise, honest novelty claim (what is reused from capabilities, DIFC/provenance, and sagas — and what is genuinely new) are in Related Work and Novelty; the design paper is the Whitepaper v1. The core authority claim — a derived capability can only ever be a subset of its intent, and delegation can only attenuate — is not just asserted: it is machine-checked by exhaustive enumeration over the capability space in dezh-kernel::authority (cargo test -p dezh-kernel).

flowchart LR
    Console["Capability-scoped console"] --> Client["Foreground client task"]
    Client -->|typed IPC| VBlk["U-mode virtio-block daemon"]
    VBlk -->|explicit MMIO + DMA grants| Disk["QEMU raw disk image"]

    Kernel["Small kernel boundary"] --> Console
    Kernel --> Client
    Kernel --> VBlk
    Kernel --> Registry["Service registry"]
    Registry --> VBlk

    SDK["SDK .dzp package"] --> Pkg["Transactional package store"]
    Pkg -->|service-mediated sectors| VBlk
    Pkg --> App["U-mode app / Dezh-IR app"]

More diagrams: docs/ARCHITECTURE_DIAGRAMS.md

The shortest useful path is:

python tools/review/run_full_review.py --quick

That command builds the review surface, runs host checks, boots both QEMU targets, and emits a transcript for the RISC-V demo path.

Prerequisites:

• Rust stable
• Python 3.10+
• QEMU:
  • qemu-system-riscv64
  • qemu-system-x86_64

Install Rust targets:

rustup target add wasm32-unknown-unknown
rustup target add riscv64gc-unknown-none-elf
rustup target add x86_64-unknown-none

Manual path:

RISC-V smoke test with a real temporary disk image:

python tools/ci/qemu_smoke.py riscv64 \
  --kernel dezh-boot/target/riscv64gc-unknown-none-elf/debug/dezh-boot \
  --qemu qemu-system-riscv64

SDK package lifecycle acceptance:

python tools/ci/sdk_test.py \
  --kernel dezh-boot/target/riscv64gc-unknown-none-elf/debug/dezh-boot \
  --qemu qemu-system-riscv64

Release tags build public review artifacts and a GitHub Container Registry review environment at ghcr.io/alisalimi77/dezh-review-env:<tag>. This is a GitHub Packages/GHCR image, not a Docker Hub image. See release process and packages and releases.

Inside the RISC-V console:

version
about
status
services
tasks
ipc-typed-demo
ipcstat
install run
apps installed
app-run lab
calc 7 + 5
vault-put demo-secret
vault-get
pkg-list
pkg-store
pkg-review hello
pkg-versions hello
pkg-gc
cairn-demo
cairn-commit note hello
cairn-log note
cairn-rollback note 1
cairn-verify note
agent
bench-all
halt

cairn-demo walks the full F2 flow: two commits, the log, a bad write, a one-step rollback, an integrity re-hash, and a cross-namespace request that the storage service denies based on kernel-attested sender capabilities.

The SDK acceptance test covers the deeper package lifecycle:

• install .dzp
• reboot and run again
• deny undeclared capability
• transactional remove
• recover interrupted journal states
• quarantine suspicious state
• reject corrupt journal until explicit recovery
• update package
• deny silent cap escalation
• allow cap escalation only with an explicit flag
• rollback to previous checkpoint
• pin/unpin lifecycle changes
• explicit physical cleanup with pkg-gc run

Dezh makes no bare "faster than X" claims. What has been measured so far (method and caveats in dezh-boot/BENCH.md):

• A Dezh capability check (the authorization decision itself) costs ~0.98 ns (native host build, i7-13650HX); the Linux getpid syscall floor on the same CPU is ~49 ns (WSL2 glibc wrapper). These are two different primitives, not a like-for-like effect comparison: a real Dezh effect also pays an ecall trap, so the honest, narrow reading is only that the authorization decision is nearly free relative to the privilege-boundary trap any OS pays — not that a mediated effect is "50× cheaper." No end-to-end speed claim is made until ecall+check vs syscall+check is measured on the same platform (see BENCH.md).
• The Dezh kernel ecall round-trip measures ~1 µs under QEMU emulation, which is not comparable to native numbers and is reported only for completeness.

See docs/REPO_STRUCTURE.md for the full map.

High-level layout:

• RISC-V QEMU is the primary bare-metal target today.
• The x86_64 kernel boots from an ISO and runs Dezh-IR packages, but is still thin: it has an exception IDT but no returnable interrupt path yet (no timer, IRQs, or scheduler on x86). The rich interactive surface — console, scheduler, IPC, Cairn, Pol — is RISC-V only.
• The block driver uses QEMU legacy virtio-mmio.
• DMA isolation is modeled through page-table discipline and fixed grants; real IOMMU integration is future work.
• Package checksums are deterministic v0 checks, not production signatures.
• App bundles and package limits are intentionally small for reviewability.
• The installer initializes a prototype disk layout; it is not a production boot media installer yet.
• Formal verification, side-channel hardening, production networking, graphics, and real hardware bring-up are out of scope for the current prototype.

Dezh is ready for architectural review as an executable OS prototype. The most useful feedback areas are:

• capability and authority model clarity
• whether the user-space driver boundary is in the right place
• typed IPC/service contract shape
• package lifecycle and recovery semantics
• how to turn intent/effect accountability into a stronger OS primitive
• gaps before a serious external review package