# your.os

> Your work, wherever you are. Terminals, files and notes on every machine you own, from any browser, and nobody in between can read them.

Each page is markdown at its own path plus .md; these pages are the project's spec. Why holds the stories; each part of Features holds promises, a heading ending in its slug, with why it matters and a Proof line; How it works holds how each part keeps them. Components are self-closing tags such as <Sealed />, filled in when the site is built, and can be skipped; compare.json holds the comparison's data.

## Pages

- [your.os](https://youros.dev/index.md): Your work, wherever you are. Terminals, files and notes on every machine you own, from any browser, and nobody in between can read them.
- [Why](https://youros.dev/why.md): The problem your.os is for, who it's for as stories with what would show each worked, what it won't do, what isn't done yet, what we haven't solved, and how it compares.
- [Features](https://youros.dev/features.md): What your.os promises, part by part, each promise one sentence with why it matters, joined by a line to the story it serves, its proof one press away.
- [How it works](https://youros.dev/how-it-works.md): Five ideas (node, log, pipe, session, service), what happens when you type into a terminal on a machine across the world, and how each part keeps its promises.
- [Features: First minute](https://youros.dev/features/first-minute.md): From arriving to a terminal on your own laptop, in a browser tab, inside a minute, with nothing typed first. Everything else is built backwards from this.
- [Features: Shell & notes](https://youros.dev/features/shell.md): Notes, pages, apps and the shell itself are documents that people and agents edit together, live, as in a shared doc: their words, styles, layout and components. An edit is data, never code, so it can break nothing but what it edits, and you can always get back to a screen that works. The editor is built and runs between tabs of one browser: try it, then open it again in a second tab.
- [Features: Files](https://youros.dev/features/files.md): Your files stay where they are, in the formats your tools read, and sync between your devices with history and merging, without converting a single file. Leave your.os and the folder is just a folder.
- [Features: Machines](https://youros.dev/features/machines.md): A terminal, files and anything else a machine does, from any of your devices, through any network, with the machine itself deciding who may.
- [Features: Your devices](https://youros.dev/features/devices.md): Every laptop, server, browser and agent of yours is a key, and your account is the signed list of which keys are yours and what each may do. Add one from a device you trust; revoke one from any other.
- [Features: Browsing](https://youros.dev/features/browsing.md): Someone else's site, signed in, from any of your devices, without its script ever running where your keys are. There is one way to do it: a real browser in a box on one of your nodes, shown in a pane. None of it is built.
- [Features: Access](https://youros.dev/features/access.md): Who may do what, for every caller: your devices, your machines, the services and extensions on a node, an agent's MCP client, someone else's node. One rule covers them all: a caller is a key, it carries a chain of grants from your account, and the node holding what it asks for checks the call itself. None of it past call/chain and call/narrows is built.
- [Features: MCP](https://youros.dev/features/mcp.md): An agent on your machine, Claude Code, Codex or anything else that speaks MCP, reaches your nodes through the node it runs beside, as a client of its own, with the grants you gave it and nothing more. It is off until you turn it on. None of it is built.
- [Features: Building](https://youros.dev/features/building.md): How your.os's own pages and apps are made, edited and shipped: this site and the shell are files on a machine, drawn by the same renderer that builds them, edited in the OS like any note, and released through the same gate as any code. For us first; a library for anyone's site, later. None of it is built: the site is still rendered by its own build.
- [Features: Network](https://youros.dev/features/network.md): Whatever forwards your traffic can't read it unless you granted it that, what is sealed today stays sealed, and a network that changes under you doesn't drop what you were doing.
- [Features: Relay](https://youros.dev/features/relay.md): A relay forwards sealed frames by key and reads nothing else. You can run your own or use ours, and leaving ours costs a setting.
- [Features: Core](https://youros.dev/features/core.md): The core is what you have to trust, so it is short enough to read: it holds keys, checks authority, seals and forwards, and everything else is a service.
- [Features: Browser](https://youros.dev/features/browser.md): A browser tab is your least trusted device: whatever its origin serves runs with its key. Later, a hostile page gets little, the network can stop being the page's source, and interception is noticed. None of it is built.
- [Features: Sandbox](https://youros.dev/features/sandbox.md): Code nobody vouches for (a browser full of other people's pages, an extension someone else wrote) runs on a node in a box: it sees only what it was given, reaches only what it was allowed, and every connection it makes is written down where you can read it. None of it is built.
- [Features: Trust](https://youros.dev/features/trust.md): What you have to trust, for what, and what stops each part from turning on you. Most of the limits are promises in other parts; this part maps them, and holds the ones about releases: how new code reaches your devices.
- [Features: How we know](https://youros.dev/features/proof.md): A promise is only as good as the test that would catch it broken, and this site can't claim more than the code does.
- [How it works: First minute](https://youros.dev/how-it-works/first-minute.md): The flow is four steps:
- [How it works: Shell & notes](https://youros.dev/how-it-works/shell.md): A page is a tree: each node names a component from the app's source, with its props, its styles and its text. The tree lives in a CRDT, so anyone can edit it at once and every copy ends the same. The editor draws the tree with the real components, so the page works while you edit it, and an edit only ever changes the tree, never the code.
- [How it works: Files](https://youros.dev/how-it-works/files.md): The files service on a node watches a folder and keeps a Loro doc beside it. The spikes (files-sync, git-roundtrip, git-import and shallow, in spikes/) tried each part; what they found is in their READMEs, and what they couldn't solve is under Open.
- [How it works: Machines](https://youros.dev/how-it-works/machines.md): A service is a name bound to a handler, in the first release a process on a local socket, given the verified caller, the verb, its arguments and a stream. The node checks the call (access.md), then hands it over.
- [How it works: Your devices](https://youros.dev/how-it-works/devices.md): A node is a key and a table of handlers: a machine, a browser profile, the command line, the MCP door and a relay are all nodes. The log is the account's signed, grow-only set of node records, grants and revocations.
- [How it works: Browsing](https://youros.dev/how-it-works/browsing.md): A profile is a browser's cookie jar, history and settings, and it is a box of its own on one node (Sandbox). In it runs one real Chrome, headed on a display of its own, with a tab per pane. The pane is a view of that tab: what it shows travels over the same sealed session as everything else, and what you type travels back naming what you aimed at.
- [How it works: Access](https://youros.dev/how-it-works/access.md): A holder is the node that has what a call asks for. Every call reaches a holder through a session (network.md), so it arrives with a verified key, and the holder answers one question about it from its own copy of the log: may(key, class, resource, now), which says allow, ask or no. No server is asked, so it works offline (log/sync-before-serve).
- [How it works: MCP](https://youros.dev/how-it-works/mcp.md): MCP is a service that ships with every node (D-4), off until turned on. It makes no decisions of its own: each client is a key (access.md, Keys for everything that calls) and each tool call becomes one call to a service, on this node or another, as that key, checked by the node that holds what it asks for.
- [How it works: Building](https://youros.dev/how-it-works/building.md): Three ways a page gets drawn, one renderer for all of them:
- [How it works: Network](https://youros.dev/how-it-works/network.md): A pipe is a channel to another node; a session is the sealed conversation that runs over whichever pipes there are.
- [How it works: Relay](https://youros.dev/how-it-works/relay.md): A relay is a node that forwards sealed frames by key. It is the one pipe every node can always open, so it is also the one place availability depends on, and whoever runs it sees who talks to whom, when and how much. Ours adds what running it takes, such as limits by plan, metering, TURN and names on our domain, and never a change to the wire (D-16).
- [How it works: Core](https://youros.dev/how-it-works/core.md): The core is sans-IO Rust, native on machines and WebAssembly in the browser, so the guarantees are the same on anything that can hold a key, from an ESP32 up.
- [How it works: Browser](https://youros.dev/how-it-works/browser.md): A browser trusts whatever its origin serves over TLS, and a network that can mint certificates for that origin, such as a proxy with its own certificate authority, can serve a page that uses the key (Core). A plain page can't stop that, so three things, later (D-21).
- [How it works: Sandbox](https://youros.dev/how-it-works/sandbox.md): The sandbox is a service on a node that makes boxes and is the only way anything gets one. A box is a set of Linux namespaces (user, mount, pid, network, ipc, uts), a seccomp filter and a cgroup, made by the node as the user it runs as. The node holds the box's network end, so it is the gate, and writes the audit. A browser profile (Browsing) and an extension instance are both boxes; nothing else in the node makes one.
- [How it works: Trust](https://youros.dev/how-it-works/trust.md): Keeps: trust/base-small, trust/reproducible, trust/public-log, trust/tiers, trust/base-approved, trust/urgent-fix, trust/widen-asks, trust/undone-on-failure
- [How it works: How we know](https://youros.dev/how-it-works/proof.md): Stories, promises, design, code and tests are joined by names, and the site is built from those names when it is built.
- [Choices](https://youros.dev/how-it-works/choices.md): Each choice your.os made, why, and what it was chosen over.
- [Privacy](https://youros.dev/privacy.md): What your.os counts, what it never keeps, and why there is no cookie and no banner.

## Optional

- [Everything in one file](https://youros.dev/llms-full.txt)
- [Compare data](https://youros.dev/compare.json)