system README

The project's README from github.com/PhreshOS/system. As one markdown file: README.md.

PhreshOS

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.

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

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:

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.

Terminal, Files, and Settings on the PhreshOS Desktop

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.

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.

system (PhreshOS/system)

Searching Database…

282 ·GitHub
System
What is this?PhreshOS is an open-source, self-hosted system that runs on a machine you control and serves a browser-based Desktop for using apps ('Programs') built with web technologies.
Is this an app, or more like an operating system platform?It's a full system, not just a library: a background service (the System) that manages Programs, permissions, storage and sign-in, plus the Desktop UI served over the browser. Programs themselves are built separately using the provided SDKs.
How do I get PhreshOS running?With Node.js 24.15+ on macOS or Linux, a single install command sets up the System as a user service, starts it, and prints the Desktop's address; the first visit creates the owner account. You can also try the live demo, which gives a disposable Desktop for an hour with nothing to install.
What do I need installed to run it?Node.js 24.15 or newer is required to install and run the System. For building from source or developing Programs, you also need Bun 1.3.
Does it fully work on Windows?Not yet — the System itself installs and runs on Windows, but some Programs don't work correctly there.
Does my data stay on my own machine?Yes — PhreshOS is self-hosted, so the System and the data of your Programs run on the machine you install it on rather than a third-party server.
What exactly is a 'Program' in PhreshOS?A Program is an app built on the System with its own Server and Client Endpoints; the System gives it a place to run, sign-in, storage, communication, and permissions, so the Program only needs to hold its own logic.
Can an AI agent use the same apps as me?Yes — an AI agent can use the same Programs through the phresh command line and SDKs at the same time a human uses them from the Desktop.
Does this repo contain everything, including the SDKs and CLI?No — this repo is only the System and Desktop. The SDKs (core, client, server, node), React bindings, the component library, the phresh CLI, and the website each live in separate related repositories.
How would I build my own Program for PhreshOS?You use the web tools you already know (JS/web frontend plus a server) together with the Server/Client/Node SDKs and the phresh CLI, which builds Programs and talks to the running System.
What are similar projects?puter, PiG, executor, claude-code, daedalOS, wigolo, oh-my-pi, Airsec
Which topics is it in?desktop-environment, bun, sdk, ai-agent, command-line-tool, framework, agent, tool, server, nodejs, typescript, self-hosted
Creator
PhreshOS
Size
34.9 MB
Stars
282
Updated
CommitOct 15Releasev0.8.6Oct 15
Age
1mo
Commits · 90 Days