Install and Self-Host PhreshOS on macOS or Linux

What PhreshOS is and what the installation creates

PhreshOS describes itself as an open-source, self-hosted system for applications built with web technologies. It runs on the machine where you install it, keeps its Programs running there, and provides a Desktop that you open from a browser. The browser displays state managed by the System, but it does not hold that running state itself.

The project uses the term Program for an application built on the System. PhreshOS provides shared platform functions such as owner authentication, communication between Programs, storage, uploads, logs, permissions, and process management. A Program can have both a browser interface and a server component. The server can continue running on the host even when no browser window is open.

Everything visible on the Desktop, including elements such as Settings, the file manager, and the wallpaper, can itself be a Program built on the System. This design lets Programs share one sign-in and use System-managed communication and permissions instead of separately implementing those foundations.

Installed System versus repository development mode

This tutorial focuses first on the standard installed System. That path installs the published @phreshos/cli package and runs phresh system install. It is the appropriate path when you want to evaluate or self-host PhreshOS rather than modify the PhreshOS source.

The repository also documents a contributor workflow. Development mode requires Bun 1.3 and Node.js 24.15 or newer, stores its data in a storage/ directory inside the repository, and starts the Desktop on the first free port beginning at 5300. An installed System uses ~/.phreshos by default and uses ports beginning at 4300. The project says these modes can run side by side.

The current project evidence includes release v0.8.5, but the repository still labels PhreshOS experimental. A numbered release does not imply production readiness or a long-term compatibility commitment.

Prerequisites for macOS and Linux

The current PhreshOS README advertises installation on macOS, Linux, or Windows. Windows is outside the scope of this macOS and Linux guide. We do not claim that Windows is unsupported or that particular Programs fail there because the supplied current project documentation does not establish those limitations.

Install Node.js from an appropriate official path

PhreshOS currently requires Node.js 24.15 or newer. Check the version resolved by your terminal:

node --version

Continue only if the response is version 24.15 or newer. Node.js 22, Node.js 20, or a 24.x version below 24.15 does not satisfy the stated minimum. Check npm as well:

npm --version

If Node.js is absent or too old, use the official Node.js download page to choose a current installation method for macOS or Linux. The Node.js project also maintains package-manager installation guidance. After installation, open a new terminal and repeat both version checks.

There is no single package-manager command that is correct for every macOS or Linux host. Distribution repositories can expose different Node.js versions, and shell-based version managers can select a different runtime in each account or terminal. The practical requirement is that the same shell used for npm install and phresh resolves Node.js 24.15 or newer.

Plan the owner-account initialization

The first visit to a new PhreshOS installation creates its owner account. Complete that workflow locally before providing any public route to the Desktop. This prevents an uninitialized owner-creation page from being intentionally exposed while you are still configuring the System.

Before adding Localtonet, confirm the exact local address, create the owner, test a fresh sign-in, and decide what non-critical data is appropriate for an experimental installation. Remote connectivity should be the final stage, not part of initial account creation.

Install and start PhreshOS

The standard installation published on the PhreshOS website and in the repository consists of two commands. The first installs the command-line interface globally. The second installs the System as a service of the current user, starts it, and prints the Desktop address.

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

The printed Desktop address is usually:

http://localhost:4300

Use the address printed by your installation rather than substituting the usual value. The project describes installed Systems as using ports from 4300, so another port can be selected when the expected port is unavailable or a different port has been configured.

What persists after installation

The project explicitly says phresh system install installs the System as a service of your user and starts it. It is therefore not merely a foreground process attached to the installation terminal. Closing that terminal should not be necessary to keep the installed service alive.

The supplied primary documentation does not state a universal persistence guarantee for every macOS and Linux login configuration. In particular, it does not confirm in the extracted material whether the user service starts before login, survives logout on every supported host, or automatically starts after every reboot. Those behaviors can depend on the service registration created by the current CLI and the operating system's user-service rules.

Test the behavior you need on the actual host. After local setup, close the installation terminal and verify the Desktop again. If unattended restart behavior matters, perform a controlled reboot during evaluation and verify both PhreshOS and any Localtonet client before relying on remote access.

Default data and configuration variables

An installed System uses ~/.phreshos by default. Treat this as application data rather than as a disposable package cache. Avoid partially deleting, manually editing, or moving it while the service is running.

The repository documents PHRESHOS_HOME and PHRESHOS_PORT as the variables that choose another home directory or port. However, the supplied installation evidence does not show the exact supported procedure for persisting those variables into an already installed macOS or Linux user service. Exporting a variable in one interactive terminal does not prove that a separately managed background service will inherit it.

If the global command is unavailable

If npm reports success but the shell says phresh is not found, close and reopen the terminal first. Then verify that your shell includes the executable location used by the active npm installation.

This often occurs when a host has multiple Node.js installations or a version manager that was not initialized in the current shell. Avoid repeatedly installing the CLI under different users. Determine which node and npm commands are active, then keep the global CLI associated with that environment and user.

Create the owner account and verify the local Desktop

A successful command exit is not enough to verify a self-hosted web application. Test the HTTP endpoint, complete the first-visit owner flow, and confirm that authentication works from a fresh browser context.

Why local verification comes first

Local verification separates application failures from tunnel failures. If the Desktop does not load directly on the PhreshOS host, a public tunnel cannot repair it. Localtonet forwards requests to a configured local target. It does not install, start, reconfigure, or heal PhreshOS.

Start on the host because localhost always refers to the device making the connection. Entering http://localhost:4300 on another computer asks that other computer for port 4300. It does not reach the PhreshOS host.

The same rule applies to our client. If Localtonet runs on the PhreshOS host, a loopback target refers to the correct machine. If our client runs elsewhere, it needs an address and port reachable from that other device. The current PhreshOS material supplied for this article does not establish an official LAN-binding procedure, so running both services on the same host is the clearest supported arrangement for this tutorial.

Local acceptance checklist

• The installer prints a Desktop address.
• The exact printed address opens on the PhreshOS host.
• The first visit allows you to create the owner account.
• The Desktop renders rather than showing only a blank or partial page.
• A fresh browser session reaches the expected sign-in boundary.
• The owner credentials work in that fresh session.
• Closing the installation terminal does not terminate the installed service.
• A controlled reboot test succeeds if reboot persistence is required for your use case.

These checks establish that the basic installation and browser workflow function on your host. They do not prove production readiness, release-to-release data compatibility, recovery guarantees, or compatibility with every Program.

Operate, update, diagnose, and remove the installed System

The current PhreshOS README says its Installation documentation covers updating, stopping, removing the System, and changing where it keeps its data. The extracted primary material supplied for this revision does not include the exact lifecycle commands from that linked page. It also does not provide verified commands for status, restart, service logs, diagnostics, or persistent reconfiguration.

What is currently confirmed

This limitation matters because PhreshOS is explicitly experimental. Command names, service layouts, migration behavior, and removal semantics can change. A guessed removal command or hand-edited service definition could leave application data behind, remove more than intended, or create a second service using a different home directory.

Maintenance sequence

Even when the exact current service command must be taken from the project's installation guide, the safe operational order is clear:

1. Stop the Localtonet tunnel so maintenance is not exposed publicly.
2. Verify which PhreshOS installation, user, data directory, and port you are operating.
3. Use the lifecycle command documented for the installed PhreshOS CLI release.
4. Preserve logs or diagnostic output before removal or destructive recovery.
5. Perform the update, configuration change, or removal.
6. After starting the System, test the local Desktop and owner sign-in again.
7. Restart the Localtonet tunnel only after local acceptance checks pass.

Backups and restore expectations

The documented default installed data location is ~/.phreshos. That identifies the normal storage directory, but it does not establish that copying the directory while the service is active produces an application-consistent backup. The supplied project material does not document a snapshot command, restore command, or compatibility guarantee across versions.

Operationally, avoid treating a live file copy as proven recovery protection. Use the project's currently documented stop procedure before taking a host-level copy when possible. Keep backups outside the PhreshOS host and test restoration in a separate evaluation environment before depending on them.

Preserve important source projects and irreplaceable files independently of the System data directory. Public reachability through a tunnel does not improve backup consistency, restore behavior, or application maturity.

Create Programs or run PhreshOS from source

Create a first Program

After the installed System works, the project documents this Program-development workflow:

phresh create my-program
cd my-program
phresh dev

The generated Program is intended to provide a window and a server that can run in your System while you edit it. This workflow is separate from installing PhreshOS itself. You do not need to create a Program to verify the Desktop or expose the Desktop through Localtonet.

Program servers can continue running on the machine without an open browser. Applications can use System-managed communication, storage, uploads, logs, and permissions. Review permission requests carefully, especially when a Program asks to reach host files, networks, commands, or other Programs.

Run the System repository in development mode

Contributors who intentionally want to change the PhreshOS source need Bun 1.3 and Node.js 24.15 or newer. Clone the official repository using your preferred Git workflow, then run the documented commands from its working directory:

bun install --frozen-lockfile
bun run dev

Development mode stores data in storage/ within the repository and serves the Desktop on the first free port beginning at 5300. This differs from the installed System, which uses ~/.phreshos and ports beginning at 4300.

If both modes run simultaneously, use the address printed by the process you intend to test. Do not infer the mode solely from a nearby port number, and confirm the exact endpoint before attaching a public tunnel.

These Bun commands belong to the repository development workflow. They are not prerequisites for the standard global CLI installation.

Expose the verified PhreshOS Desktop with Localtonet

After PhreshOS works locally and the owner account exists, you can connect its HTTP endpoint to Localtonet. Our client establishes an outbound connection to a Localtonet relay server. The resulting HTTP tunnel provides a public HTTPS URL without requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

An HTTP tunnel is appropriate because the PhreshOS Desktop is served over HTTP. The tunnel points to a local IP address and port reachable from the selected Localtonet client. The simplest arrangement is to run our client on the PhreshOS host and use the host and port from the address printed by PhreshOS.

For the current dashboard fields and sequence, use our HTTP tunnel documentation. Process-type availability and subscription details can vary, so do not assume that every option is available in every account.

A Random Sub Domain is the simplest initial testing choice because it does not add custom DNS configuration to the troubleshooting path. If you later use a custom domain, follow the current Localtonet documentation for the required DNS configuration rather than guessing record types or values.

Verify both sides of the tunnel

Test more than the appearance of a single page. Open the public URL in a browser that does not already hold the local owner session. Confirm that the page loads, the authentication boundary remains present, sign-in works, and the Desktop remains usable.

Then stop the tunnel and verify that the public route is no longer available. Confirm that direct local access still works. If local access succeeds but public access fails, inspect the selected Localtonet device, client connection, relay selection, tunnel state, local target, and assigned URL. If both local and public access fail, troubleshoot PhreshOS first.

Security boundaries for an experimental web desktop

A public URL makes the configured PhreshOS endpoint reachable from the internet. It does not make PhreshOS production-ready, add application authorization, limit Program permissions, create backups, or guarantee vulnerability protection. PhreshOS remains responsible for its owner sign-in and application behavior, while Localtonet provides the route to the selected local HTTP endpoint.

Prefer short exposure windows during evaluation

Because PhreshOS is experimental, keep the System local by default and run the public tunnel only when remote testing is needed. Stop it immediately afterward. A shorter exposure period does not fix application vulnerabilities, but it reduces the time during which the endpoint is reachable.

Record which Localtonet tunnel is active, which device runs it, and which local port it targets. This is especially important when the installed System and a source-development instance run together. Accidentally targeting the development port can expose unfinished code or test data.

Troubleshooting installation and remote access

The installer rejects the Node.js environment

Run node --version in the same terminal used for installation. The current requirement is Node.js 24.15 or newer. If you upgraded but still see an older version, open a new terminal and inspect your shell path or version-manager selection.

npm reports a global installation permission error

Correct the global package location or Node.js installation for your user. Do not repeatedly alternate between administrator-level and user-level installation attempts. Doing so can place the CLI under a different account or executable prefix from the one intended to own the PhreshOS service.

The phresh command is not found

Reopen the terminal and confirm that globally installed npm executables are available to the active shell. Also verify that npm belongs to the same Node.js installation checked earlier. Multiple Node.js installations commonly produce mismatched global command paths.

The Desktop refuses the local connection

Confirm that you copied the exact address printed by phresh system install and that you are opening it on the PhreshOS host. Do not assume port 4300 if another address was printed. If the endpoint previously worked, consult the current official Installation guide for the supported status, diagnostic, and start procedure because exact post-install lifecycle commands are not present in the supplied primary extract.

The page loads incompletely

Test with a fresh browser session and determine whether the failure occurs directly at the local URL. If it fails locally, stop investigating Localtonet. Preserve available logs and note the PhreshOS release, Node.js version, operating system, printed endpoint, and reproduction steps before making destructive changes.

The local URL works but the public URL does not

1. Confirm that the Localtonet client is running and connected.
2. Confirm that the tunnel is assigned to that client device.
3. Confirm that the tunnel has been started rather than only created.
4. Confirm that the local IP address and port match the working PhreshOS endpoint.
5. Confirm that you are testing the public URL assigned to that tunnel.
6. If the client runs on another machine, remember that its localhost is not the PhreshOS host.

The public URL opens the wrong local service

Stop the tunnel and compare its target with the exact address printed by the intended PhreshOS instance. The installed System uses ports beginning at 4300, while repository development mode uses the first free port beginning at 5300. Other applications can also occupy nearby ports.

The tunnel worked and later became unavailable

A Localtonet tunnel is available only while the selected client remains connected and the tunnel is running. Check whether the host slept, shut down, changed networks, ended a relevant user session, or stopped the Localtonet client. Verify PhreshOS locally as a separate check.

Another device cannot reach the local address

A localhost address is local to the machine where it is opened. The current PhreshOS evidence supplied here does not document a supported LAN-binding procedure. For this workflow, run the Localtonet client on the PhreshOS host rather than improvising a network-listening change.

The owner-account creation page appears publicly

Stop the Localtonet tunnel immediately. Complete owner initialization locally and verify sign-in from a fresh session before restoring public access. If another person may have completed the owner flow, do not add sensitive data. Follow the current PhreshOS recovery or removal guidance rather than assuming the installation remains trustworthy.

A changed home directory or port has no effect

An environment variable exported in an interactive shell may not be inherited by an already installed user service. Do not create a second installation or move the original directory until you have confirmed the project's current procedure for applying PHRESHOS_HOME or PHRESHOS_PORT to the service.

Frequently asked questions