your.os .md

How it works

Five ideas, and nothing else. Here is what happens when you type ls into a browser tab and a laptop at home answers.

  1. You type ls. The tab seals it with keys only it and your laptop share.
  2. The relay forwards it. It sees a destination key, a number and sealed bytes. Nothing else.
  3. Your laptop opens it. It checks the tab's grant against your log, then runs the command.
  4. The answer comes back. Sealed the same way. Change networks and the session carries on.

Node

Anything with a key is a node: your laptop, a server, a browser tab, the command line, an agent's door, a relay. A node is a key plus the list of things it can do. The same core runs on all of them, written in Rust, native on machines and WebAssembly in the browser.

Log

Your account is a signed, grow-only list of which keys are yours: this laptop was added on Tuesday, that phone was revoked on Friday. Every node keeps a copy. A node learns its peers' keys only from the log, never from a server, so no server can slip in a key of its own.

Pipe

A pipe is any way bytes get from one node to another. There is always a WebSocket to a relay, so you are reachable from any network that allows the web. When a faster path appears, a direct WebTransport or WebRTC connection joins it. The relay forwards by key and sees only sealed bytes.

Session

Two nodes shake hands once, with X25519 and ML-KEM together. They check each other's keys against the log and get session keys that belong to no pipe. Every message after that is numbered and sealed on its own. When your wifi drops and the phone moves to 5G, the session carries on over the new pipe without a new handshake, and anything unacknowledged is sent again.

Service

A service is what a node does when asked: a terminal, files, sync, a browser. The node verifies who is calling and what they were granted, then hands the request to the service. The core stays short enough to read in a sitting, and everything else is a service.

Where it can break

We write down where each idea fails, because that's what you're trusting.

  • A stolen laptop is a valid key until its revocation reaches the machine holding your data.
  • The relay is where availability depends, and it sees who talks to whom, when and how much, though not what.
  • A machine that is offline misses revocations, so grants are short-lived.
  • Lose every device that can sign for your account and you lose the account. Add a second one early.