umbrel Documentation

File: README.md Copy Chapter

Installing umbrelOS Copy Chapter

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 Copy Section

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

Building apps for umbrelOS Copy Chapter

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

License Copy Chapter

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 [email protected].

umbrel.com

File: containers/tor/README.md Copy Chapter

☂️ Tor

A simple Docker image for Tor

🛠 Build Tor Docker image Copy Chapter

Build Copy Section

docker build -t getumbrel/tor .

Run Copy Section

docker run --rm -u 1000:1000 -e HOME=/tmp getumbrel/tor

File: containers/app-proxy/README.md Copy Chapter

☂️ App Proxy

App-proxy is a transparent HTTP proxy to add authentication to Umbrel apps. Every HTTP request and Websocket connection goes through the proxy and each request has the session token checked for validity. The session token is set via App-auth. It runs by-default as a containerized service.

🚀 Getting started Copy Chapter

If you are looking to run Umbrel on your hardware, you do not need to run this service on it's own. Just download Umbrel OS and you're good to go.

🛠 Running app-proxy Copy Chapter

Make sure umbrel-manager and app-auth are running and available.

Development and testing Copy Section

cd $UMBREL_ROOT/containers/app-proxy/test
./test.sh docker-compose.app1.yml

Within the test directory there are several test apps to test different functionality such as Websocket and SSE with the proxy.

Environment variables (dev/testing) Copy Section

The following environment variables are set in .env file of the project's root:

File: containers/app-auth/README.md Copy Chapter

☂️ App Auth

App-auth is a simple authentication and redirection system for Umbrel apps. It ensures (where applicable) that apps are password (and OTP) protected. It runs by-default as a containerized service.

🚀 Getting started Copy Chapter

If you are looking to run Umbrel on your hardware, you do not need to run this service on it's own. Just download Umbrel OS and you're good to go.

🛠 Running app-auth Copy Chapter

Make sure umbrel-manager are running and available.

Development and testing Copy Section

cd $UMBREL_ROOT/containers/app-auth/test
./test.sh

Environment variables (dev/testing) Copy Section

The following environment variables are set in .env file of the project's root:

File: packages/ui/app-auth/README.md Copy Chapter

Local testing

Make sure umbreld is running

cd packages/umbreld
npm run dev

Then in another terminal

cd packages/ui
pnpm run app-auth:dev

Go to localhost:3001 and make sure you're logged out.

Then, assuming transmission is installed and running, open:
http://localhost:2001/app-auth/?origin=host&app=transmission&path=%2Ftransmission%2Fweb%2F

In production, it would be:
http://localhost:2000/?origin=host&app=transmission&path=%2Ftransmission%2Fweb%2F

Login with password and 2fa should work and you should be redirected to the right page.

File: packages/ui/src/routes/README.md Copy Chapter

Non-route files and folder should be prefixed with an underscore. This is to prevent confusion.

File: packages/ui/README.md Copy Chapter

umbrelOS UI

Getting umbrelOS running locally Copy Chapter

Prerequisites Copy Section

npm and pnpm is installed.

First install pnpm. One way is via brew install pnpm on mac, assuming you have homebrew installed.

Clone the repo and checkout the `mark` branch Copy Section

git clone -b mark [email protected]:getumbrel/private-umbrel.git

Go into the repo Copy Section

cd private-umbrel

Get frontend running Copy Section

1. cd packages/ui
2. pnpm install
3. pnpm run dev

Get backend running Copy Section

1. Get back to the root of the repo and cd into umbreld: cd packages/umbreld
2. Make the dir for the data: mkdir data
3. npm install
4. npm run dev

Sharing semi-publicly (on Mac) Copy Chapter

1. Get the CLI
2. Add this to your .zshrc or .bashrc:

alias tailscale="/Applications/Tailscale.app/Contents/MacOS/Tailscale"

3. Run tailscale serve:

tailscale serve http:3000 / http://127.0.0.1:3000

4. For production:

tailscale serve http:4000 / http://127.0.0.1:4000

Running on HTTP for now. HTTPS would be a bit more complicated. The prod build is especially important for getting a true sense of performance on mobile since the dev build will have extra cruft.

Decisions / common patterns

`keyBy` Copy Chapter

Using remeda instead of lodash because it's more typesafe. Lodash keyBy adds 14kb after minifcation and doesn't return proper types.

`foobarDescription` format for static data Copy Chapter

For lots of static data we want to maintain order and have it indexed. For a nav menu, we want a slug and a string for each element. We call them descriptions if it's an array with each element having an id and label. So we do this:

const navDescriptions = [
  {
    id: 'home',
    label: 'Home'
  }
  {
    id: 'about',
    label: 'About'
  }
] as const // <-- important

const navDescriptionsKeyed = keyBy(navDescriptions, 'id')

Adding view transition support to elements Copy Chapter

EX:

Box

You can then search the repo for viewTransitionName to find them all

Event handler naming in React components Copy Chapter

Use onFooBarClick rather than onClickFooBar

No barrel files Copy Chapter

Vite doesn't like them. Haven't tested how bad they are for performance, though.
https://vitejs.dev/guide/performance#avoid-barrel-files

tRPC Copy Chapter

Prefer trpcReact over trpcClient because it lets you manage error and loading state, caching, and invalidation. More info here: https://trpc.io/docs/client/vanilla#when-not-to-use-the-vanilla-client

TROUBLESHOOTING

TypeScript errors in code that don't make sense in VSCode Copy Chapter

Restarting the TS server via the command palette fixes it. I haven't run into a situation where this doesn't fix it.

File: scripts/backup/README.md Copy Chapter

Automatic Encrypted Backups

The backups are encrypted client side before being uploaded over Tor and are padded with random data. Backups are made immediately as soon as the channel state changes. However, Umbrel also makes decoy backups at random intervals to prevent timing-analysis attacks.

These features combined ensure that the backup server doesn't learn any sensitive information about the user's Umbrel.

• The IP address of user is hidden due to Tor.
• User's channel data are encrypted client side with a key only known to the Umbrel device.
• Random interval decoy backups ensure the server can't correlate backup activity with channel state changes on the Lightning network and correlate a backup ID with a channel pubkey.
• Random padding obscures if the backup size has increased/decreased or remains unchanged due to it being a decoy.

Due to the key/id being deterministically derived from the Umbrel seed, all that's needed to fully recover an Umbrel is the mnemonic seed phrase. Upon recovery the device can automatically regenerate the same backup id/encryption key, request the latest backup from the backup server, decrypt it, and restore the user's settings and Lightning network channel data.

There is currently no way to disable backups or recover from them in the dashboard yet. Both of these features will be introduced in the coming updates.