GitHub - PhreshOS/system: An open-source system for apps built with web technology. You and your AI agents use them from one desktop in the browser.

An operating system for software built with web technologies.

Website · Documentation · Live demo · Releases

PhreshOS runs on the machine you install it on, keeps your Programs running there, and gives you a Desktop in the browser to use them from. Programs are built with the web tools you already know. The System gives each of them a place to run, one sign-in, communication with other Programs, storage, and permissions, so a Program only holds its own logic.

Everything on the Desktop, from the file manager to Settings and the wallpaper, is a Program built on the System, not part of it.

This repository is the System: the service that runs on your machine, and the Desktop it serves.

What Programs get

A place to run. A Program's Server keeps running on the machine, whether or not a browser is open.
One sign-in. The owner signs in to the System. Programs never handle accounts, sessions, or connections.
Communication. Programs ask, publish, and listen, between their own parts and between Programs, without setting up a transport.
Permissions. The System decides what each Program may reach.
Any browser. Open the Desktop from any browser that can reach the machine, and the same Programs are there, as you left them.
Agents alongside you. An AI agent uses the same Programs through the phresh command line and the SDKs, at the same time as you use them on the Desktop.

Try it

The live demo gives you a disposable Desktop for an hour, with nothing to install.

To install PhreshOS on macOS, Linux, or Windows, you need Node.js 24.15 or newer:

npm install --global @phreshos/cli
phresh system install

The command installs the System as a service of your user, starts it, and prints the Desktop's address, usually http://localhost:4300. The first visit creates the owner account. See Installation to update, stop, or remove it, or to change where it keeps its data.

Then create your first Program:

phresh create my-program
cd my-program
phresh dev

What the System does

The System owns the running state of PhreshOS:

Programs, their Processes, and the Server and Client Endpoints they run;
communication between Endpoints, Services, and Programs;
authentication of the owner and of every connection;
permissions, storage, uploads, and logs;
the Desktop: Windows, layers, the plane of views, and the Appearance.

The browser shows this state; it does not hold it. A Desktop, a Node script, and the phresh command all reach the same System, through contracts defined in @phreshos/core. See The System for the full model.

Development

You need Bun 1.3 and Node.js 24.15 or newer.

bun install --frozen-lockfile
bun run dev

dev runs the System from source, with its data in storage/ in this repository and the Desktop on the first free port from 5300. An installed System uses ~/.phreshos and ports from 4300, so both can run side by side. PHRESHOS_HOME and PHRESHOS_PORT choose another home or port.

Command	Does
`bun run check`	Type-checks the source
`bun run build`	Builds the server and the Desktop into `dist/`
`bun run test`	Runs the tests in `tests/`
`bun run verify`	Runs `check`, `build`, and `test`, including a test that packs the release, installs it in a temporary folder, and boots it
`bun run pack`	Builds the release archive and its checksum

The source has three parts: source/server is the System, source/client is the Desktop, and source/shared holds what both use.

Related repositories

Repository	Role
core	The contracts shared by every part of PhreshOS
client	The SDK for a Program's Client Endpoint, in its Window
server	The SDK for a Program's Server Endpoint
node	The SDK for Node.js code that reaches a running System
react	React bindings for the SDKs
react-ui	The component library the Desktop and Programs draw with
cli	The `phresh` command: installs the System, builds Programs, and reaches the running System
website	phreshos.com and its documentation

Contributing