PhreshOS

An open-source, self-hosted system for apps built with web technologies.

Website · Documentation · Live demo · Releases

!The PhreshOS Desktop: Terminal showing phresh fetch, Files, and the Map with windows beyond the view

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.

[!NOTE]

PhreshOS is still experimental and not yet ready for production use.

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

• One sign-in. The owner signs in to the System. Programs never handle

• Communication. Programs ask, publish, and listen, between their own parts

• Permissions. The System decides what each Program may reach.
• Any browser. Open the Desktop from any browser that can reach the machine,

• Agents alongside you. An AI agent uses the same Programs through the

Try it

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

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

[!NOTE]

Windows is not fully supported yet. The System installs and runs there, but

some Programs do not work.

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.

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

See CONTRIBUTING.md. To report a vulnerability privately, see SECURITY.md.

License

MIT. Copyright © 2026 Zohayr SLILEH.