Why

#The problem

Ask where your notes live, who can read them and what happens if the company holding them changes its mind. The answer is usually one you didn't choose. Reaching your own laptop from somewhere else means trusting whoever is in between; an agent given your password gets everything; and changing a page or an app means waiting on a developer.

your.os makes it yours to choose, for each thing you own:

• Where it lives. This laptop, that server, a phone, a cloud machine you rent. More than one, kept in sync, and movable later. A server of ours is just another machine you trust some amount.
• Who may use it. A person, a device, an agent, a service, each a key granted exactly what it needs, for as long as it needs it, and revocable from any of your devices.
• How it is sealed. Plaintext where you want speed and search, ciphertext everywhere it only passes through.
• What you can change. Notes, pages and apps are documents anyone you let in edits live, and an edit is data that can't run.

#Who it's for

Each story is someone your.os is for, what they do with it, and how we'd know it worked for them. A line off the right margin goes down to each part of Features that serves it.

#Your machines and files

#Alex reaches the laptop at home from a caféseen?↓ First minute · What is open on first boot Alex is in the laptop's terminal within the minute, with nothing to sign up for.↓ First minute · Your name, and keeping it Alex keeps the account by picking a name, once there's something worth keeping.↓ Machines · What you can do Alex's shell on the home laptop, from a café, carrying on when the wifi drops.↓ Machines · Its desktop Alex uses the home laptop's desktop from a café while the laptop sits locked on the desk.↓ Machines · Staying up to date The laptop at home takes every fix without Alex going back to it, and never mid-session.↓ Your devices · Add a machine says which systems it runs on, and what each needs Alex knows before installing whether the laptop at home is supported.↓ Your devices · Joining Alex adds the home laptop with one pasted line.↓ Browsing · One browser, on a node Alex's signed-in tabs are on the laptop at home, and open from the phone where they were left.↓ Browsing · Using it as a browser The tab on the laptop behaves like a tab, from a phone too.↓ Access · Between nodes, and inside one A machine reaching another machine is held to what it was granted, as any caller is.↓ Network · Pipes Alex gets through from any network that allows the web, and directly where the network lets it.↓ Network · Lost packets and network changes The café wifi drops, the hotspot takes over, and Alex's shell carries on.↓ Relay · The wire, version 1 The relay is the one way through that every network allows.↓ Core · The core depends on crypto crates only The same core runs on the laptop at home and in Alex's browser tab.↓ Sandbox · Making a box needs no root The machine Alex pairs in a minute, as an ordinary user, can run a browser box.

Alex opens your.os in a browser, pastes one line into the laptop at home, and is in its terminal. The café wifi drops, the phone's hotspot takes over, and the shell carries on.

Worked if someone new reaches their own machine's terminal in under a minute, with no sign-up, and a dropped network doesn't lose their place.

#Alex loses a phone, and it opens nothingseen?↓ First minute · Your name, and keeping it A name never reused means a stale key in some old browser can't be handed to someone else.↓ Your devices · Nodes The lost phone is one key: revoking it touches nothing else.↓ Your devices · The log The revocation reaches the machine with Alex's notes before it answers anyone.↓ Access · A session loses a grant the moment it expires or is taken back Taking back a grant stops a session already open, not only the next one.↓ Network · Sessions A stolen phone can't stand in for another key, or read what it recorded.↓ Relay · Version 2 The revocation waits at the relay for the machine that was away.↓ Browser · A hostile page gets little A copied browser profile opens nothing, and can't add a device by itself.

The phone is gone with your.os on it. From the laptop, Alex revokes it; the server with Alex's notes refuses it the next time it calls, even if that server was offline when Alex did it, and no other device needs adding again.

Worked if the lost device is refused everywhere it tries, and nothing else had to be set up again.

#Jo's notes and code are on every device, and still filesseen?↓ Shell & notes · Devices and agents edit one page at once, through the relay Jo's notes are the same on the phone and the laptop, edited on both.↓ Shell & notes · Plain files Jo's notes open in the editor, and on disk they are still the same markdown files.↓ Files · What's kept Jo chooses which folders follow her, sees at a glance which are on every device, and a laptop full of builds doesn't fill the phone.↓ Files · Finding your way Jo stars the folders she works in and gets back to them in one tap, from any of her browsers.↓ Files · A folder and its doc Jo's notes are plain files in folders, edited with any tool, the same on every device.↓ Files · Git Jo's code syncs like any folder, and git still works exactly as it did.↓ Files · History Jo can go back to last Tuesday, and a phone left in a drawer for two months still syncs.↓ Your devices · Settings: yours, this device's, this moment's Jo's theme and workspaces follow Jo; the phone keeps its own zoom.

Jo edits notes on the phone on a train and code on the laptop at home; both merge when they meet. The files stay files in folders, git still works, the theme follows Jo and each screen keeps its own zoom.

Worked if Jo never loses an edit or a commit, and never converts a file to use it.

#Pages and apps

#Sam changes the café's page without waiting on anyoneseen?↓ Shell & notes · Changing the page Sam changes the hours, the menu and a photo by pointing at them on the page.↓ Shell & notes · A real app The booking form keeps taking bookings while Sam edits around it.↓ Shell & notes · Yours Sam's page stays Sam's: in Sam's browser and files, with no server to trust.↓ Shell & notes · Safe to change Whatever Sam changes, there's a way back to a page that works.↓ Access · Nodes that face outward Sam's page is served by a node granted the published version, and nothing else of Sam's.↓ Building · Structure and words are files The rectangles and words of a page or an app are a file Sam can open, point at and change.↓ Building · Drawn in a frame of its own Sam's page can look like anything CSS can do, and still can't reach past its rectangle.

Sam runs a café whose site a developer built. On a Monday Sam changes the opening hours, moves the menu above the gallery and swaps a photo, on the page itself, while the booking form keeps taking bookings.

Worked if someone who has never seen the editor makes those three changes in their first ten minutes, without help, and nothing on the page breaks.

#A team gets a launch page ready togetherseen?↓ Shell & notes · Editing together Three people on one page in launch week, one of them on a train: editing together is that week.↓ Shell & notes · Changing the page One person changes the colours while another rewrites the words.↓ Shell & notes · Versions Nobody loses work: anything can be gone back to.↓ Shell & notes · Only granted writers' edits are taken in Only the team's edits reach the page; a reader can't push one.↓ Browsing · A pane's comments, picking and screenshots work on a site They comment on the site itself, a vendor's dashboard included.

Three people work on one page the week before a launch: one rewrites the words, one changes the colours, one adds sections on a train with no signal. They comment on the page instead of sending screenshots, and each undoes their own mistakes.

Worked if at the end nobody has lost work, and nobody has had to ask who changed something.

#Priya adds what only code can do, and stops being asked for wordsseen?↓ Shell & notes · Source Priya reads what an edit really changed, as text.↓ Shell & notes · A real app Priya's booking widget comes from the app's source, built like any code.↓ Shell & notes · A page is readable text in git Priya reviews a page's changes in the pull request already in use.↓ Shell & notes · An edit merged in git comes back as edits Priya edits a page in git, and it merges with the live edits.↓ Shell & notes · Plain files An edit in the editor is a diff of only its own lines in Priya's pull request.↓ Files · Git Priya commits and reviews in git as always; nothing merges code behind git's back.↓ Building · One renderer Priya sees the page in the pane exactly as it will ship, because one renderer draws both.↓ Building · Apps, edited where they live Priya changes an app's layout, words and styles in the OS, and its behaviour in code beside them.

Priya is the developer. They build a booking widget in the app's source, and after a rebuild it's in everyone's library. They read the page's changes as text in git, like any other change.

Worked if requests to change words and colours stop reaching them, and they review a page's changes in the pull request they already use.

#Sam lets an AI help, and decides what it seesseen?↓ Shell & notes · AI The AI sees only the section Sam picks, and its edits wait to be taken.↓ Shell & notes · No server ever reads your page Sam can say what was sent and to whom, because nothing else leaves.↓ Shell & notes · A grant on one doc reaches no other An agent let into one doc can read nothing else.↓ Shell & notes · Safe to change An AI that could restyle the screen still can't make deny look like allow.↓ Your devices · The log The agent's grant to one folder until Friday is an entry in the log, revocable from any device.↓ Browsing · An agent with a browser Sam can let an agent use one throwaway profile, and see every page it opened.↓ Access · Every caller is a key The agent Sam lets in is a key of its own, so what it may do is what Sam granted that key.↓ Access · What a grant can say One folder on the laptop, read but not write, until Friday, is one grant.↓ Access · Allow, ask, deny What the agent changes waits for Sam, and Sam answers from whichever device is to hand.↓ Access · What's written down Sam can say what each agent read, changed and asked for.↓ MCP · Turning it on Sam turns it on from settings, sees what the agent will get, and pastes one line into the agent.↓ MCP · What a client sees The agent sees only the verbs its grant allows, and what it changes waits for Sam.↓ Sandbox · The gate Sam can see every host the agent's browser dialled.↓ Sandbox · Extensions An agent's tool from someone else runs with the folder and hosts it was given, and nothing more.

Sam selects the menu section and asks for it to be friendlier; the suggestion arrives beside the page, and Sam takes two changes of three. Later Sam lets an agent into one folder on the laptop until Friday. Each sees what Sam gave it and nothing else, and what it changes waits for Sam.

Worked if Sam keeps the suggestions they want, and can say what each AI saw, what it changed and until when it could.

#Anyone deciding to trust it

#Someone checks every claim before trusting itseen?↓ Browsing · What a site may reach What a browser on the node may dial is stated, and every connection it made is there to read.↓ Access · Every caller is a key Nothing is trusted for saying who it is; every answer comes from a chain anyone can check.↓ Building · One renderer That the page in the editor is the page that ships is checked on every build, not claimed.↓ Network · Anything that forwards sees only {to, ciphertext} What a relay sees is checked byte by byte in a test anyone can run.↓ Relay · Version 2 A relay proves who it is by the account's own log, not by a certificate authority.↓ Relay · Who runs the relay Anyone can run the relay and check it against the same suite as ours.↓ Core · The core is short The code they have to trust is small enough to read in a sitting.↓ Browser · Native mode On a network they don't trust, they can run the release they checked, not whatever the network serves.↓ Browser · Noticing interception A work network's inspection box is noticed and reported, not trusted in silence.↓ Sandbox · A box What a box can touch is a short list, stated, and tested from inside the box.↓ Sandbox · The gate Every connection a box made is there to read, with what the gate decided.↓ Trust · What you trust, and for what They can see, part by part, what each piece could do if it turned, and which promise stops it.↓ Trust · How new code arrives An update can't be made for them alone, and can't change what everything rests on without someone being able to see it first.↓ How we know · The tests Each claim names the test that shows it, and whether it passed.↓ How we know · This site They answer 'does it really do this?' from the site alone.

An engineer deciding whether to use your.os, or to work on it, wants to know whether it really does what this site says: which test shows each promise, whether it passed, which code keeps it, and how small the part they have to trust is.

Worked if they answer "does it really do this?" from the site alone, without asking us.

#What it won't do

• Un-read. What someone already read, they keep. Revoking decides what happens next.
• Search on our servers. We can't index what we can't read. Search runs on your machines.
• Make a browser tab as safe as a laptop. Any script on a page can read that page's key, so a tab is your least trusted device and is granted the least.
• Let an edit run code. Behaviour comes only from source, through a build; an edit is data.
• Replace your developer. What only code can do stays code, and reaches the library through the developer.

#Not yet

• Seen working. Every story above is a guess until someone does it; nobody has yet.
• Your browser as a device, and the first minute. The core, sessions, accounts, the relay and a Linux machine's terminal and files are built and tested; the browser node and the end-to-end test that fails if a relay sees anything you typed are next.
• Editing between devices. The editor's promises hold between tabs of one browser. Between devices waits for docs to travel over the relay; until then a page moves as a saved file.
• Later: an agent door (MCP), remote browsing, your own domain, and machines as small as an ESP32.

What could still go wrong is under each part of How it works, such as the editor's risks.

#Open problems

What we want solved and haven't: what a solution would have to do, and where we'd start.

#Proving it's you without giving the secret away

Alex is at a borrowed laptop, with no phone and no key: only what Alex knows. Whatever is typed or clicked there may be recorded, and a password typed once on a recorded keyboard is a password given away. Can you prove you know a secret so that a recording of the proof doesn't let anyone prove it again?

A solution would:

• Survive being watched. A recording of one login, or of many, doesn't let anyone log in later.
• Need nothing carried, and be learnable by anyone, in a minute a login.
• Be checked by your own machine, not by us.

It can't make that laptop safe while you use it; whatever it shows you, it sees. So a login there gets little, briefly, and your other devices hear about it. Adding a device never happens this way: it takes a passkey or a device you already trust.

Where we'd start:

• Questions about what you did lately. Your machine knows what you worked on, so it asks an open question ("what were you fixing on Thursday evening?") and checks the answer against what happened. A recorded answer is stale by next week, and there's nothing to learn. Open: people close to you know the answers too, and the checker must compare facts, not be talked into a yes.
• Sums done in your head (Blocki, Blum, Datta and Vempala, Towards Human Computable Passwords). You learn a secret list of pictures and digits; a login shows rows of pictures, and you answer each row with a digit from a few lookups and two additions. Two pictures in the row pick which other picture counts, using your secret, so a recording gives no equations to solve: hundreds of recorded rows aren't enough. Open: learning a hundred pairs takes days, and one slip fails a row.
• Rows answered wrong on purpose. A secret rule, such as "any row with this picture, type any digit", makes some recorded answers garbage, and a watcher can't tell which. Our idea, untested.
• Access that grows with each check. An emailed code and a PIN let you read for an hour; answering more lets you do more; each step is announced.

#Compare

You may already use something that does part of this. So far this compares the editor with page builders; tools for reaching your machines and syncing files aren't written up yet. Find your tool, or what you need; each tool says what it is better at, and when to use it instead. Built from one file (compare.json), every row dated and marked searched (checked against a source that day) or from memory (not yet re-checked).

#By tool

yes partly no planned here, not built · hover a column for what it means

#By need

#What we found

No tool we found is open source, keeps edits as data, merges concurrent moves safely and keeps the page off any server, on a real app. The nearest are Builder.io, shipped and closest in feel, where edits become code on a hosted service, and Puck, whose model of data plus your own components is ours, for one editor at a time. Not finding a tool is not proof there isn't one: tell us.