Running Roost

Roost is a self-hosted app platform. You download a single binary, run it, and you have a personal cloud with real apps — chat, music, photos, and more — running on hardware you own.

Installation

Roost is distributed as a single binary. No Docker, no config files, no reverse proxy setup. Download the binary for your platform and run it.

macOS

Install with Homebrew:

brew tap roost/homebrew https://codeberg.org/roost/homebrew
brew install roost

Or download the binary directly from the releases page.

Linux (x86_64)

Debian / Ubuntu (apt)

# Add the Roost apt repository
curl -fsSL https://roost.club/apt/roost.gpg | sudo gpg --dearmor -o /usr/share/keyrings/roost.gpg
echo 'deb [signed-by=/usr/share/keyrings/roost.gpg] https://roost.club/apt stable main' | sudo tee /etc/apt/sources.list.d/roost.list
sudo apt update
sudo apt install roost

Updates are installed with the usual sudo apt update && sudo apt upgrade.

Debian / Ubuntu (manual .deb)

# Download the latest .deb package from the releases page
sudo dpkg -i roost_*.deb
roost serve

Fedora / RHEL

# Download the latest .rpm package from the releases page
sudo rpm -i roost_*.rpm
roost serve

Direct download

# Download from releases, make executable, and run
chmod +x roost
./roost serve

Raspberry Pi

Recommended hardware: Raspberry Pi 4 or 5 with at least 2 GB RAM. A USB SSD is strongly recommended over an SD card for reliability and performance.

Step 1: Prepare your Pi

Flash Raspberry Pi OS Lite (64-bit) using the Raspberry Pi Imager. Enable SSH during the setup wizard so you can connect remotely.

Step 2: Connect and update

ssh pi@raspberrypi.local
sudo apt update && sudo apt upgrade -y

Step 3: Install Roost

Download the Linux ARM64 package from the releases page: 

# Using the .deb package (recommended)
wget https://codeberg.org/joshbuddy/roost/releases/download/latest/roost_linux_arm64.deb
sudo dpkg -i roost_linux_arm64.deb

# Or download the binary directly
wget https://codeberg.org/joshbuddy/roost/releases/download/latest/roost_linux_arm64.tar.gz
tar xzf roost_linux_arm64.tar.gz
chmod +x roost

Step 4: Run Roost

roost serve

Roost will start on https://localhost:3000. Open this URL from any device on your network (use your Pi's IP address, e.g. https://192.168.1.42:3000).

Step 5: Run on startup (optional)

Create a systemd service so Roost starts automatically when your Pi boots:

sudo tee /etc/systemd/system/roost.service > /dev/null <<EOF
[Unit]
Description=Roost
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi
ExecStart=/usr/bin/roost serve
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable roost
sudo systemctl start roost

Tips for Raspberry Pi

  • Use a USB SSD. SD cards wear out quickly with database writes. A cheap USB SSD is far more reliable and faster.
  • Give Roost a static IP. Set a static IP in your router's DHCP settings so your Pi is always reachable at the same address.
  • Point DNS at your Pi. If you enable Roost's built-in DNS server, set your router's DNS to your Pi's IP. This lets all devices on your network access apps by hostname (e.g. chat.home.local).

First run

When you first start Roost, it will guide you through a short setup:

  1. Create your admin account (username and password).
  2. Configure your domain (optional — defaults to localhost).
  3. Install your first apps from the catalog.

Once setup is complete, you can access the admin panel at /admin-view to manage apps, users, and settings.

Installing apps

Browse the Roost App Catalog to find apps. Download an app's .zip file, then install it using the CLI: 

roost load path/to/app.zip

The app will be available immediately. Each app runs in its own sandbox with its own database — apps can't see each other's data.

Managing users

Invite family members or collaborators from the admin panel under Users. Each user gets their own account with isolated data in each app. Users log in through the main Roost interface.

Remote access

By default, Roost is accessible only on your local network. To access it from outside your home:

  • SSH tunnel (simple): Use ssh -L 3000:localhost:3000 pi@your-pi-ip to forward the port to your laptop when away from home.
  • Domain + gateway (advanced): Configure a listener in the admin panel's Listeners tab to set up an SSH gateway with your own domain. This gives each app its own subdomain (e.g. chat.yourdomain.com).

DNS & ad blocking

Roost includes a built-in split-horizon DNS server. When enabled, it:

  • Resolves your app hostnames (like chat.yourdomain.com) to your local server's IP — no external DNS needed.
  • Forwards all other DNS queries to your configured upstream servers (defaults to 1.1.1.1 and 8.8.8.8).
  • Optionally blocks ads, trackers, and malware domains using the Steven Black unified hosts list (over 100,000 blocked domains).

Enable the DNS server in the admin panel under the DNS tab. Then point your router's DNS (or your device's DNS) to your Roost server's IP.

Backups

Roost stores all its data in a single directory. Back up this directory regularly to protect your data. You can configure automated backups from the admin panel under the Backups tab.

Updating

To update Roost, download the latest release and replace the binary. If you installed via Homebrew: 

brew upgrade roost

If you installed via .deb or .rpm, download the new package and install it the same way. Your data is preserved across updates.