Apps
Every app runs on the device. Some add a second half — a backend in the companion on your Mac — that does the heavy work and paints onto the device's screen.
An app has two halves. One runs on the device. The other, optional, runs in the companion on your Mac. Whichever half is doing the work, what you see is always the device's screen.
The two halves of an app
The pixels land here
- Sandboxed, in the device's own flash.
- Keeps running with your Mac asleep, quit, or nowhere near.
- One app runs at a time; opening another retires it.
- Real memory, a network, a sandboxed folder of its own.
- The only half that can reach your Mac.
- Can hold its own settings, kept on your Mac.
The device half
Every app ships code that runs on the device itself — sandboxed, in the device's own flash. This is the half that draws on the screen and answers your buttons. An app without it will not install.
Because it lives on the device, it keeps working when your Mac is asleep, quit, or nowhere nearby.
The companion half
An app may also ship a second half that runs inside the companion on your Mac. An app can leave it out and install unchanged.
Think of it as a backend. It runs where there is real memory, a network and a folder of its own, does the heavy work, and then paints onto the device's screen — the same screen the device half draws on. What you see is always the device. What is computing it might be your Mac.
Its own settings
The companion half can carry its own settings. An app describes a settings form, and the companion shows a Configure tab for it on your Mac. Whatever you set is saved on your Mac, never on the device. Anything sensitive — a key, a token — goes into your Mac's keychain and never travels to the device.
Two halves, different powers
The two halves are not the same kind of program. The device half owns the screen and the buttons. The companion half is the only one that can reach your Mac — a notification, the clipboard, a link, the network, a saved setting. Each can do something the other cannot.
Two runtimes, one shared floor
The halves ship as separate programs — a device.wasm, and an optional companion.wasm. The device half runs in a small interpreter built for a microcontroller; the companion half runs in a full WebAssembly engine on your Mac. They share a common floor — drawing, navigation, logging, and a message channel between them — and each then gets powers the other does not have. Only the device half can hold the screen awake or read the device's own clock. Only the companion half can reach your Mac: a notification, the clipboard, a URL, a network fetch, a stored setting. The channel between them is small: one half sends, the other receives.
Skills and connectors
An app is one of the five kinds of extension, and it leans on two of the others.
It can carry skills — short instructions that teach an agent to drive it. They ride inside the app's package and land in your Library beside it, ready to install into the agent you choose.
It can use a connector to reach an account you already have. The connector holds the key; the app is the feature that uses it. A Gmail app uses the Gmail connector to show your new mail; a calendar app uses the Calendar connector. Sign in once, and every app that needs that account shares the same door.
How much an app needs your Mac
Because the companion half is optional, an app declares how much it leans on it. There are three stances, and the app tells you which one it takes.
How much an app needs your Mac
Does it need your Mac to do its job?
- NoStandalone
- YesDoes it still do something while your Mac is away?
Does it still do something while your Mac is away?
- YesEnhanced
- NoRequired
- StandaloneRuns entirely on the device. Never shows a not-connected state.
- EnhancedWorks on its own; does more when your Mac is near.
- RequiredA thin remote for the companion. Dims to Not connected when your Mac is away.
Standalone
Runs entirely on the device. It needs nothing from your Mac, ever, so it never shows a not-connected state — there is nothing for it to be connected to.
For example: a kitchen timer, a compass, a dice roller.
Enhanced
Works on its own, and does more when your Mac is near. It shows what it has while offline, then swaps to live content the moment the companion connects.
For example: a notes card that shows the notes it saved last time, and refreshes them when your Mac comes back.
Required
Needs the companion to do anything at all. The device is a thin remote: it dims to Not connected when your Mac is away, and comes back to life when your Mac returns.
For example: a live build-status card, or one that runs the music on your Mac.
One app at a time
The device runs one app at a time. Opening a second retires the first: the outgoing app is told it is going away, then it is torn down and the new one loads in its place.
What comes installed
Your device comes with Settings — the one app you did not install and cannot remove. Everything else, you install yourself.
See Install an app for how a bundle gets onto the device.
An agent can put an app on the device too
There is one more way an app can reach the device: an outside agent can draw UI — or register a whole app — live from your Mac, without installing anything to the device's flash. That is MCP.