---
title: "Bramble"
url: https://manvsmidi.com/projects/bramble/
category: experiment
status: wip
date: 2026-09-05
tags: [rust, os, graphs]
related: [conclave, collusion-wiki, evonet]
---

# Bramble

> A hobby x86_64 kernel in no_std Rust that keeps all of its state in one typed graph. Processes, memory, capabilities and wait queues are nodes and edges, and a running kernel can be dumped, checked and diffed.

Experiment · In progress · 2026-09-05

- [Source](https://github.com/sadovsky/bramble)

Bramble is an operating system experiment built around one idea: the kernel has no separate tables for processes, page mappings, handles or run queues. There is a single typed, directed graph, and everything else is an index derived from it.

## The graph

Eight node kinds (Root, Cpu, Process, Thread, AddressSpace, MemoryObject, Endpoint, Device) and seven edge kinds:

| Edge | Means |
|---|---|
| Owns | lifetime; forms a tree rooted at Root |
| Holds | a capability, with rights and a slot number |
| InSpace / Maps | which address space, which memory is mapped where |
| Ready | a thread is on a CPU's run queue |
| Waiting | a thread is blocked on an endpoint or device |
| Named | a name, walked like a path |

The design doc pushes back on the original brief where it wouldn't survive contact with x86. Authority is one hop, not reachability. Lifetime is an ownership tree, so destroying a node revokes everything under it without a garbage collector. Pick-next is "first Ready edge", never a traversal. The graph is the source of truth and the thing you inspect, not what the page-fault handler walks.

## What works

Boots under Limine and OVMF in QEMU. Ring 3 processes, preemption, synchronous IPC with capability transfer, revocation, lazy mapping and demand-paged shared memory. An unprivileged program can read the whole kernel state out as bytes, and a host-side tool checks it against the page tables, draws it with Graphviz and diffs two snapshots. It can also ask the 1977 take-grant question of a live kernel: could this process ever obtain a capability to that object?

![Graphviz drawing of the kernel graph: Root owning memory objects, three processes with their threads, address spaces, endpoints and capability edges](https://manvsmidi.com/_astro/kernel-graph.B5Du3u1J.png)
*The live kernel state read out by an unprivileged program during a boot, then drawn on the host: 56 nodes, 107 edges.*

`docs/DEVLOG.md` is the best way in. It's written for someone who has never built a kernel, and each entry covers how the problem is normally solved, what Bramble does instead and what broke.

## Running it

Needs QEMU, OVMF, xorriso and Graphviz; the toolchain is pinned.

```bash
./scripts/build-iso.sh
./scripts/smoke.sh     # headless boot → serial.log, screen.png, graph.png
```

## Connected projects

- [Conclave](https://manvsmidi.com/projects/conclave/index.md): linked
- [collusion-wiki](https://manvsmidi.com/projects/collusion-wiki/index.md): shared tags: graphs
- [EvoNet](https://manvsmidi.com/projects/evonet/index.md): shared tags: graphs