Important

LuckyCoders fork — not official umbrelOS

This repository is a community fork of getumbrel/umbrel. It is maintained in parallel with upstream while Pi external-storage fixes are not yet merged upstream. Do not use Settings → Software Update on a device running this build — that installs the official release and removes these changes.

What we fixed (Raspberry Pi) No auto-format at boot — a USB drive is never wiped when umbrelOS boots from SD Umbrel stays on SD — apps and data remain on the SD card even if an empty USB drive is attached External USB in Files — drives mount under Files → External (ext4, exFAT, NTFS) Network WebDAV — connect WebDAV servers (NAS, Nextcloud) via Files → Network using rclone Cloud storage — connect Dropbox and Google Drive via Files → Network (rclone + OAuth) Power safety — external drives are unmounted on undervoltage or USB I/O errors UAS blacklist — improved USB stability on Raspberry Pi 4

How this differs from upstream Official umbrelOS This fork External storage disabled on Pi Enabled in Files Boot script may format a blank USB Boot script never formats USB Pi USB treated as unsupported in UI Server-side support via API

Install this fork on an existing Raspberry Pi 4

Prerequisite: umbrelOS 1.7.x already running from SD (bootFlow: rpi-tryboot). Apps and data on the data partition are preserved.

1. Build or download umbrelos-pi.update

• GitHub Actions: Build umbrelOS Pi → Run workflow → download the artifact
• Or locally: cd packages/os && npm run build:pi → build/umbrelos-pi.update

2. Copy to your Pi and install

scp umbrelos-pi.update umbrel@<pi-ip>:/tmp/

ssh umbrel@<pi-ip>
sudo rugix-ctrl update install \
  --reboot set \
  --insecure-skip-bundle-verification \
  /tmp/umbrelos-pi.update

3. After reboot, if everything works

sudo rugix-ctrl system commit

4. Verify

grep "Umbrel data stays on the SD card" /opt/umbrel-external-storage/umbrel-external-storage
# Plug in a USB drive — it should appear in Files → External within ~10 seconds

Tip

Use a powered USB hub for hard drives on Pi 4. For future updates from this fork, repeat the rugix-ctrl update install steps with a new umbrelos-pi.update artifact — not the in-app updater.

---

umbrelOS

A beautiful home server OS for self-hosting
umbrel.com »

Get an Umbrel Pro or Umbrel Home for the full experience, or install umbrelOS on a Raspberry Pi 5 or any x86 system for free.

At Umbrel, we believe that everyone should be able to enjoy the convenience and benefits of the cloud, without giving up ownership and control of their data.

To achieve our vision, we're building a new kind of a home server OS. Instead of paying ransoms for storing your data on someone else's computer while they auction it off to advertisers — you can now easily spin up a server and self-host your data and services at home.

Just like the cloud, but one that you own and control.

Installing umbrelOS

umbrelOS is designed for the Umbrel Pro and Umbrel Home, where it includes first-class support for all features. On other devices (like Raspberry Pi or x86 systems), it’s freely available with core functionality, but support and feature availability are best-effort due to hardware differences.

For a detailed feature breakdown, see our comparison guide.

Installation guides

• Install umbrelOS on a Raspberry Pi 5
• Install umbrelOS on any x86 system
• Install umbrelOS in a VM

Building apps for umbrelOS

If you're interested in building an app for umbrelOS or packaging an existing one, please refer to the Umbrel App Framework documentation.

License

umbrelOS is licensed under the PolyForm Noncommercial 1.0.0 license. TL;DR — You're free to use, fork, modify, and redistribute Umbrel for personal and nonprofit use under the same license. If you're interested in using umbrelOS for commercial purposes, such as selling plug-and-play home servers with umbrelOS, etc — please reach out to us at partner@umbrel.com.

umbrel.com