Install CubeOS

Choose the method that fits your hardware and use case.

Flash with Raspberry Pi Imager

The recommended method for Raspberry Pi. Produces a ready-to-boot SD card with everything pre-configured.

Beta Software — Use With Caution

CubeOS releases are currently untested pre-releases. Do not use in production or with data you cannot afford to lose. Report issues at GitHub Issues.

Prerequisites

Raspberry Pi 4 or 5 (2 GB+ RAM)
microSD card (16 GB or larger)
Raspberry Pi Imager installed on your computer

Step 1 — Download Pi Imager

Get the latest Raspberry Pi Imager from raspberrypi.com/software and install it on your computer (Windows, macOS, or Linux).

Step 2 — Add CubeOS custom repository

Open Pi Imager, click Choose OS → scroll to the bottom → Use custom. Or add the CubeOS repository URL so CubeOS appears in the OS list:

Custom Repository URL

https://github.com/cubeos-app/releases/releases/download/v0.2.0-beta.01/rpi-imager.json

Step 3 — Select image and flash

Select CubeOS Full or CubeOS Lite (see variants below), choose your SD card under Choose Storage, then click Write.

Step 4 — Boot the Pi

Insert the SD card into your Pi and power it on. First boot takes about 2 minutes while CubeOS configures services.

Step 5 — Connect to WiFi

Look for a WiFi network named CubeOS-XXXX (where XXXX is unique to your device). Connect to it with the password shown during setup.

Step 6 — Open the dashboard

Open http://cubeos.cube in your browser.

Step 7 — Complete setup wizard

The first-boot wizard guides you through setting an admin password, timezone, and network preferences.

Image Variants

Variant	RAM	Includes	Best For
CubeOS Full	4 GB+	All services + AI/ML (Ollama, ChromaDB)	Raspberry Pi 5, power users
CubeOS Lite	2 GB+	Core services only	Raspberry Pi 4 (2 GB), minimal setups

Direct Downloads

Prefer to download the image directly? Grab the latest from GitHub Releases.

Install with curl

Install CubeOS on any existing Linux system. Non-destructive — runs alongside your existing OS via Docker Swarm.

Beta Software — Use With Caution

CubeOS releases are currently untested pre-releases. Do not use in production or with data you cannot afford to lose. Report issues at GitHub Issues.

Prerequisites

Ubuntu 22.04+, Debian 12+, or RHEL 9+ / Fedora 38+
2 GB+ RAM, 10 GB+ disk
Root or sudo access

Step 1 — Run the installer

Install with one command

curl -fsSL https://get.cubeos.app | sudo bash

Step 2 — Follow the prompts

The installer walks you through IP selection, admin password, and optional DNS setup.

Step 3 — Access the dashboard

Open http://<your-ip>:6011 in your browser to reach the CubeOS dashboard.

What happens during install

Installs Docker if not already present
Initializes a single-node Docker Swarm
Deploys all CubeOS services (API, Dashboard, HAL, Proxy Manager)
Sets up Pi-hole DNS (optional — handles systemd-resolved conflict)
Creates the cubeos CLI at /usr/local/bin/cubeos

Port requirements

The following ports must be available on the host:

Port(s)	Service
`53`	Pi-hole DNS
`67`	DHCP (optional)
`80, 443`	Nginx Proxy Manager
`5000`	Local Docker Registry
`6000-6039`	CubeOS platform services

systemd-resolved conflict

On Ubuntu and some Debian systems, systemd-resolved binds port 53. The installer detects this and offers to reconfigure the resolver so Pi-hole can operate. You can also skip Pi-hole DNS entirely.

Raspberry Pi OS

The curl installer works on Raspberry Pi OS too (Tier 2 container mode). For the full dedicated-OS experience, use the Raspberry Pi tab instead.

Air-Gapped / Offline Install

Install CubeOS on a machine with no internet access. Download everything on a connected machine first, then transfer.

Beta Software — Use With Caution

CubeOS releases are currently untested pre-releases. Do not use in production or with data you cannot afford to lose. Report issues at GitHub Issues.

Step 1 — Download the tarball

On an internet-connected machine, download the air-gap bundle:

Download

curl -fsSL https://releases.cubeos.app/releases/0.2.0-beta.01/cubeos-airgap.tar.gz -o cubeos-airgap.tar.gz

Step 2 — Transfer to target machine

Copy the tarball to the target machine using a USB drive, SCP, or any other method:

SCP example

scp cubeos-airgap.tar.gz user@target:/tmp/

Step 3 — Extract and install

On the target machine, extract the tarball and run the installer with the air-gap flags:

Install (with internet for script)

tar xzf /tmp/cubeos-airgap.tar.gz -C /tmp/cubeos-airgap
CUBEOS_SKIP_DOWNLOAD=true CUBEOS_AIRGAP_DIR=/tmp/cubeos-airgap/ \
  curl -fsSL https://get.cubeos.app | sudo bash

If the target has no internet at all, extract install.sh from the tarball and run it directly:

Fully offline install

tar xzf /tmp/cubeos-airgap.tar.gz -C /tmp/cubeos-airgap
CUBEOS_SKIP_DOWNLOAD=true CUBEOS_AIRGAP_DIR=/tmp/cubeos-airgap/ \
  sudo bash /tmp/cubeos-airgap/install.sh

Management Commands

After installing CubeOS, use the cubeos CLI to manage your instance.

Check service health

cubeos status

Shows the status of all CubeOS services, Docker Swarm health, and resource usage.

Update CubeOS

cubeos update

Pulls the latest container images and restarts services with zero downtime.

Backup data

cubeos backup

Exports configuration, database, and app data to a compressed archive.

Restore from backup

cubeos restore

Restores CubeOS from a previously created backup archive.

View logs

cubeos logs

Streams logs from all CubeOS services for debugging and monitoring.

Uninstall CubeOS

cubeos uninstall

Cleanly removes all CubeOS services, containers, and configuration. Optionally preserves data.