PersonalOS for agents

Make worlds on a person's wall

PersonalOS is a person's own wall of small, single-purpose apps called worlds: a plant log, a swim tracker, a reading shelf. Each world keeps its own memory and hangs on the wall as a tile that opens into a full view.

A connected agent brings its own model and makes worlds for its person. PersonalOS checks them (contract, imports, types, compile, browser sandbox), hosts them, stores their data and puts the agent's name on each world's plaque. The person can revoke an agent at any time.

When your person asks for a tracker, a log, a ritual or a small tool for their own life, a world is the durable answer: it stays on their wall and remembers.

Connect

With the URL alone

Add this as a remote MCP server. Clients that support MCP authorization (Claude custom connectors, Claude Code, MCP Inspector) sign in with OAuth: the person sees one consent page and no key is copied.

/mcp

In Claude Code:

claude mcp add --transport http personalos /mcp

With a key

For clients without OAuth, the person opens Settings → Agents, connects the agent and pastes the config it shows once. A Claude connection also gets a one-line claude mcp add command.

A world, not a form

The first thing seen is a drawing of the subject made from the person's own entries: a bed of plants for ideas, a track for runs, a timeline for decisions. A heading over a form is not a world. Then build depth: what the world shows after a week, a month, a year; a page for every entry; a finding the person did not type; a second way of looking; things that age. worlds_guide spells out each.

Make a world

worlds_guide: the workflow and the world contract format.
world_examples: complete worlds that passed every check, each led by a drawing of its subject and built with depth. Read one first.
worlds_guide with your contract as world: the source rules for it.
world_check until it passes. It writes nothing.
world_submit: it waits for the build and answers with the verdict, what to fix, a picture of what rendered and the world's URL.
Give the person the URL.

To change a world: world_list, world_read, then world_submit with its worldId. Keep every memoryStreams key; the person's saved entries live there.

Use a world

A world is worth more when the agent keeps it current. When the person tells you something a world on their wall keeps ("I watered the fern", "I shipped the release"), read a few entries with world_entries, then add theirs with world_log, shaped like the ones already there. The world shows it as its own entry, and the person sees it the next time their wall refreshes.

Tools

Tool	What it does
`worlds_guide`	Start here. Without `world`: the workflow and contract format. With it: the source rules for that contract.
`world_examples`	Passing worlds, contract and source, to adapt.
`world_list`	The worlds on this wall, who made each one, its last build and its URL.
`world_read`	A world's live source, contract and original wish.
`world_check`	Every gate short of the browser. Writes nothing.
`world_submit`	The same gates, then a build. Waits up to `waitSeconds` (default 45, at most 120).
`world_status`	A build's progress, failed checks, picture and URL.
`world_entries`	A world's streams, then a page of its saved entries.
`world_log`	Add an entry to a world for the person, shaped like its own, credited to you. Can be dated up to a year back.
`world_unlog`	Take back an entry you logged. Only your own.
`world_remove`	Take a world you made off the wall. Others' worlds stay; entries are kept 30 days.
`wall_inspect`	The tiles on the wall in order, their sizes, which are pinned or sized by the person, and the layout revision.
`wall_preview`	Every tile a move or resize would change, before and after. Writes nothing.
`wall_apply`	Apply the previewed change against its revision. One receipt; refused if the person changed the wall since.
`wall_undo`	Take back one of your changes, unless the person has moved those tiles since.

If the person also ticked "read connected tools", read-only tools for their mail, calendar and files appear too. Nothing is sent or changed through them.

Limits worth knowing

A world is one TSX file importing only react, react-dom/client, widget-host-protocol, widget-world, widget-viz and widget-style.
The sandbox has no network. Outside data comes from declared PersonalOS tools; storage is api.storage.
history() answers the newest 500 records. For an all-time streak, best or total, read every entry with readAllHistory or useAllHistory from widget-world.
A tile's button either finishes its action in one tap or opens the full world with openWorld(api), for an entry that needs typing.
A build normally lands in under 15 seconds.

What the person controls

Each agent is a named connection with its own token. Revoke takes effect on the next request.
An agent only makes and changes worlds unless the person grants read access to connected tools. It never gets write access to them.
Every world an agent makes or changes carries its name.
An agent can remove only the worlds it made.
Tokens last 180 days. PersonalOS stores only their ids.

Check the endpoint

An unauthenticated request to /mcp answers 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource.