umbrelOS: a home server OS you install instead of a Linux distro

What umbrelOS replaces, and for whom

The problem umbrelOS targets is not app hosting in the abstract. It is the setup work that comes before app hosting: partitioning a disk, installing a base distribution, wiring up Docker, arranging reverse proxying and TLS, and then keeping all of it patched. The project describes itself as "a beautiful home server OS for self-hosting" and frames the goal as cloud-like convenience without giving up ownership of the data.

The intended user is someone who wants a personal server that behaves like an appliance. The README points at three hardware paths: an Intel or AMD machine, a Raspberry Pi 5, or a virtual machine. It also points at two first-party boxes, Umbrel Home and Umbrel Pro, and states that the image you install on your own device is the same umbrelOS that ships on those boxes, with the same features and the same updates. That claim is the interesting part of the pitch. It means the free download is not a cut-down edition.

The audience is narrower than "anyone who self-hosts". If you enjoy assembling services from Compose files and you want to keep doing that, umbrelOS is a layer between you and the machine. It is for people who would rather not have that layer.

How umbrelOS is put together: an OS image, not a package

The most consequential design decision is stated plainly in the README: umbrelOS is a standalone operating system that installs directly onto your device, and it cannot be installed on top of an existing Linux distribution. There is no apt repository, no Docker image you run alongside your current stack. You give it a machine, or a virtual machine, and it takes over the boot.

The repository layout matches that model. Top-level entries include clients/, containers/, packages/, scripts/ and info.json, and the primary language is TypeScript. The package.json exposes scripts rather than a library entry point: dev runs ./scripts/umbrel-dev, and there are test:vm and build:remote scripts. This is the repository of an operating system product, not a reusable Node module. The clients/ and containers/ directories suggest a split between the user-facing clients and the containerised services that run on the device, which is consistent with an appliance that presents a UI while managing workloads underneath.

Because the OS owns the boot disk, the storage model follows. The README says umbrelOS boots from one drive and uses the rest for apps and data. That is a clean arrangement, and it is also why the two-drive features are gated: Storage Manager and FailSafe need two or more internal NVMe or SATA drives. On a single-disk install, those features are simply not available to you.

Installing umbrelOS on your own hardware

The README does not inline installation commands. It directs you to umbrel.com/downloads for the latest ISO and images, along with step-by-step guides for each platform. There is no shell one-liner to copy, so the first step is a download rather than a command.

Before you download, check the minimum requirements as stated for Intel and AMD devices: a dual-core CPU, 4 GB of RAM with 8 GB or more recommended, and a 32 GB drive for umbrelOS itself. On Raspberry Pi 5 the README asks you to boot from an NVMe or USB drive rather than a microSD card. For virtual machines it lists Proxmox, VirtualBox, VMware, or anything else that supports EFI boot.

If you already run umbrelOS and want the 2.0 beta, the README gives a different path: update to umbrelOS 1.7.4 or later, then open Settings > Advanced settings and turn on umbrelOS beta program. The stable 2.0 release is planned for September 22, 2026 according to the README, and 2.0.0-beta.1 was published on 2026-09-02.

The repository itself is built with npm scripts, which matters only if you intend to work on umbrelOS rather than run it. The root package.json defines the entry points:

{
  "type": "module",
  "scripts": {
    "dev": "./scripts/umbrel-dev",
    "dev:help": "npm run dev help",
    "clean:worktrees": "./scripts/clean-worktrees",
    "test:vm": "npm --prefix packages/os run build:amd64:rugix && rm -rf packages/os/rugix/build && npm --prefix packages/umbreld run test:vm --",
    "build:remote": "./scripts/remote-builder build",
    "test:remote": "./scripts/remote-builder test"
  }
}

Running npm run dev:help is the documented way to see what the development script accepts, since the README itself does not document the development workflow. Note that the build and test targets here are VM-oriented. There is no plain npm test that exercises the OS on your laptop.

Where umbrelOS is the wrong tool

The standalone requirement is the sharpest limitation, and it cuts in two directions. If you already run a Linux server with services you care about, umbrelOS is not an upgrade path for that machine. It is a replacement for it. You would be reinstalling, not layering.

Hardware gating is the second constraint, and it is easy to miss because it is buried in a sentence about features rather than a requirements table. Storage Manager and FailSafe need two or more internal NVMe or SATA drives. GPU acceleration needs an NVIDIA, AMD, or Intel GPU on an Intel or AMD machine. A Raspberry Pi 5 user gets neither of those, and a single-disk mini PC user gets the storage features only after adding a second drive. The README states these dependencies but does not document what happens when the hardware is absent beyond the implication that the feature is unavailable.

There is also a documentation gap that matters for anyone evaluating it seriously. The README covers installation and app building, and it links to the Umbrel App Framework documentation for packaging. It does not document rollback, backup of the OS itself, or what a failed update leaves behind. If your decision depends on recovery behaviour, the README will not answer it and you should treat that as an open question rather than assume it is handled.

umbrelOS compared with running your own Docker host

The obvious alternative is a general-purpose Linux server with Docker Compose, or a NAS operating system that also runs containers. The difference is not the container runtime, since umbrelOS is not shy about Docker: docker is one of the repository topics. The difference is who owns the boot and who owns the update path.

On a self-managed Docker host, you choose the base distribution, you own the reverse proxy and certificate renewal, and you decide when to patch. Nothing is hidden, and nothing is handled for you. On umbrelOS, the OS image is the product, updates arrive as OS updates, and the app layer is presented through a store. The README describes the app catalogue as the Umbrel App Store with over 300 apps, and points developers at the Umbrel App Framework documentation for packaging.

That trade is real in both directions. You gain a consistent, appliance-like experience across Intel, AMD, Raspberry Pi 5 and VMs, and you lose the ability to install umbrelOS as one service among many on a machine you already administer. If your existing server is the thing you want to keep, the Compose route is the one that preserves it. If the server is the thing you want to stop thinking about, umbrelOS is aimed at you.

Licence, maintenance and upgrade cost

umbrelOS is licensed under PolyForm Noncommercial 1.0.0, and the repository's licence field is reported as NOASSERTION, so the README and LICENSE.md are the sources to read rather than a short SPDX label. The README summarises the terms as free use, forking, modification and redistribution for personal and nonprofit use under the same licence. Commercial use, which the README illustrates with selling plug-and-play home servers with umbrelOS, requires contacting [email protected]. This is a summary, not legal advice; if your use is commercial, the licence text governs.

On maintenance, the last push to master was on 2026-09-02, and the most recent release is 2.0.0-beta.1 from the same day. Before that, 1.7.4 shipped on 2026-07-10 and 1.7.3 on 2026-05-12. The cadence is steady, and the project is not archived.

Upgrade cost concentrates in the beta path. The README tells existing users to reach 1.7.4 or later before enabling the beta program in Settings > Advanced settings, which means skipping releases is not the intended route. You are also opting into beta software on the machine that holds your data, and the README does not describe a rollback procedure for that. The stable 2.0 release is planned for September 22, 2026, so waiting is a coherent choice.

Editorial conclusion

Adopt umbrelOS if you want a self-hosted box that behaves like an appliance and you are willing to dedicate a whole machine or VM to it, and if your use is personal or nonprofit under PolyForm Noncommercial 1.0.0. Do not adopt it if you need it running on top of an existing Linux install, if you need two-drive features such as Storage Manager or FailSafe on a single-disk box, or if you intend to resell hardware with it preinstalled without talking to [email protected] first. Before you commit, check the supported-device list against your exact hardware, confirm whether Storage Manager and FailSafe matter to you, and read LICENSE.md rather than the README's summary of it.

Frequently asked questions

Official sources

1. getumbrel/umbrel on GitHub
2. Issues
3. Project website
4. README
5. Releases