PhreshOS bills itself as an operating system purpose-built for software constructed with web technologies. The project positions itself as a runtime that lives on the machine it is installed upon, maintaining programs in execution and serving a full Desktop interface through any reachable browser. Where traditional operating systems layer window management and application ecosystems atop a kernel, PhreshOS makes the system itself the programmatic substrate, with every element on the Desktop — file manager, settings, wallpaper — represented as a first-class Program rather than system chrome.
Program isolation and single sign-on
The System gives each Program a dedicated place to run, a store for its logic, and permissions that dictate what resources it may reach. Accounts, sessions, and network connections are handled exclusively by the System; no Program is tasked with authentication or transport setup. A single owner signs in to the System once, and every subsequent connection is authenticated and authorized by the runtime. This design means programs never need to implement their own sign-in flows or session management.
Program communication without configuration
Programs communicate by asking, publishing, and listening — between their own internal endpoints and across Programs — without ever configuring a transport layer. The System routes messages through contracts defined in @phreshos/core, so a Program's Client Endpoint in its Window and its Server Endpoint both speak the same protocol. This eliminates the common bootstrapping friction of discovering services, opening ports, or managing firewalls.
AI agents as first-class users
An AI agent runs alongside the human user, invoking the same Programs through the phresh command line and the available SDKs, at the same time those Programs appear on the Desktop. The agent does not occupy a separate context; it is a simultaneous user of the same runtime, with the same permissions and the same program state. This means a user could, for example, have a spreadsheet Program open in their browser while an agent concurrently queries or modifies that same Program's data through the SDK.
Installation and runtime topology
Installation requires Node.js 24.15 or newer and Bun 1.3. The command-line tool @phreshos/cli is installed globally, then phresh system install boots the System as a user-level service and prints the Desktop address, typically http://localhost:4300. The first browser visit creates the owner account. From there, phresh create my-program scaffolds a new Program, cd my-program && phresh dev starts development mode, bundling the source with Bun and making the Program immediately available on the Desktop.
An installed System stores its data under ~/.phreshos and uses ports beginning at 4300, while a development instance from source uses ports from 5300 and keeps data in the repository's storage/ directory. Both can run side by side, with PHRESHOS_HOME and PHRESHOS_PORT available for customization.
Source architecture
The repository is organized into three source trees. source/server implements the System runtime, source/client builds the Desktop interface, and source/shared contains code used by both. Eight published repositories compose the surface: core defines the contracts shared by every part, client provides the SDK for a Program's Client Endpoint in its Window, server provides the SDK for a Program's Server Endpoint, node offers a SDK for Node.js code reaching a running System, react and react-ui supply bindings and a component library the Desktop and Programs draw with, cli delivers the phresh command for installation and system interaction, and website hosts phreshos.com and its documentation.
Verifying and extending the system
Tooling includes bun run check for type-checking, bun run build to produce the server and Desktop into dist/, bun run test for the test suite, bun run verify to run check/build/test including a release-packing boot test, and bun run pack to build the release archive and its checksum. Vulnerabilities are handled through SECURITY.md, and contributions are governed by CONTRIBUTING.md under an MIT license © 2026 Zohayr SLILEH.