The open-source self-hosting OS for any hardware

What Synology DSM is for NAS, CubeOS is for self-hosters — runs on Raspberry Pi,
x86_64, ARM64 SBCs, or any Linux machine. Offline-first design, self-healing containers,
and network-transparent hardware access across every node.

Website · Documentation · Download · Community

CubeOS transforms any hardware into a self-contained server with a consumer-friendly web dashboard, one-click app store, and a unique Hardware Abstraction Layer (HAL). Plug a GPS receiver into Node 1 and a LoRa radio into Node 2 — any container on any node can access both devices through a unified REST API, as if the hardware were local. CubeOS makes hardware location irrelevant.

Built for offline-first operation, CubeOS is equally at home on your desk, in a remote field station, or aboard an expedition vehicle crossing the Sahara. Docker Swarm provides self-healing containers with automatic reconciliation — if a service crashes at 3 AM, Swarm restarts it without human intervention. A local Docker registry caches images for offline installation, so CubeOS runs reliably where "just pull the latest image" isn't an option.

Docker Swarm gives you self-healing containers, rolling updates, secrets management, and automatic workload scheduling. But it's blind to hardware. It can schedule based on CPU and RAM, but it has no idea that Node 1 has a Coral TPU plugged in, Node 2 has a Zigbee coordinator, and Node 3 has a GPS receiver. You can set node labels manually — but if someone moves the Coral from Node 1 to Node 3, the labels are wrong and your service deploys to the wrong place.

CubeOS was born from this exact frustration. Docker Swarm had the orchestration features we needed. It just couldn't see the hardware underneath it. So we built the missing layer: a Go daemon on each node that auto-discovers all connected hardware, dynamically manages Swarm node labels via the Docker API, and exposes every device through REST endpoints that any container on any node can reach over the network.

The result: Docker Swarm handles container lifecycle. The HAL gives Swarm eyes. Containers follow hardware automatically. And low-bandwidth devices like serial radios, GPS receivers, and satellite modems become network-transparent — accessible from any node in the cluster without moving the container to the device.

No other lightweight platform does this. Kubernetes solves it with Node Feature Discovery plus a constellation of device plugins and operators — hundreds of thousands of lines across dozens of projects that only work inside Kubernetes. CubeOS provides the same capability in a single binary, running on a $80 Raspberry Pi or your spare x86 box, with zero Kubernetes overhead.

CubeOS runs 800+ apps from the CasaOS ecosystem through its Compose-to-Swarm compatibility layer — giving you the same app store experience, with self-healing containers and transactional installs underneath.

Manage Docker containers, view real-time logs, monitor CPU/RAM/storage/temperature, and install apps — all from your phone or laptop browser. No terminal required. Responsive design works on any screen size.

Docker Swarm continuously monitors every service. If a container crashes, Swarm automatically restarts it. If a node goes down in a multi-node cluster, workloads redistribute. Combined with the HAL's dynamic node labelling, services with hardware constraints automatically follow their devices — move a Coral TPU from Node 1 to Node 3 and the dependent container migrates with it. This is production-grade orchestration running on a $80 Raspberry Pi or any x86 machine.

CubeOS turns your Pi into a portable network with integrated DNS and DHCP. Five modes adapt to any environment:

Connect your phone, laptop, or IoT devices to the CubeOS network and access the dashboard at http://cubeos.cube.

Bond multiple internet connections into combined bandwidth for every device on the network. Hotel WiFi too slow? Add phone tethering and an Ethernet cable — CubeOS aggregates all three transparently. LAN clients need zero configuration; the bonding is invisible.

The HAL detects WAN interfaces automatically (Ethernet, WiFi client, USB tethering) and manages MPTCP subflows at the kernel level. Hot-plug a phone via USB tethering mid-session — the new link joins the bond within seconds.

A $12 GPS module gives CubeOS sub-microsecond accurate time via PPS (Pulse Per Second), independent of any internet connection. CubeOS serves this as a Stratum 1 NTP source to every device on the WiFi network — phones, laptops, sensors, and other CubeOS nodes all get accurate time automatically.

This matters more than it sounds: without GPS time, offline deployments have no reliable clock source. TLS certificates, log correlation, sensor timestamps, radio protocols, and file sync all depend on accurate time. The same GPS module also provides position data for MeshSat, APRS beaconing, and offline maps.

Laptop-style power profiles with battery and solar-aware automatic load shedding. CubeOS reads battery state from UPS HATs and solar charge controllers (Victron VE.Direct, EPEver Modbus), then automatically manages power consumption:

Each container has a configurable priority level. When battery drops below a threshold, CubeOS stops low-priority services first and restarts them when power recovers — with hysteresis to prevent flapping. Combined with RTC wake alarms, a solar-powered CubeOS can run a duty cycle: operate during daylight hours, deep-sleep overnight.

Plug in RTL-SDR USB dongles ($10–25 each) and CubeOS turns them into dedicated receivers. The HAL auto-detects dongles and the dashboard lets you assign each one to an application:

Each application runs as an isolated Docker container with USB device passthrough. Multiple dongles = multiple simultaneous applications.

When all internet infrastructure is down — no cell towers, no WiFi, no satellite data — CubeOS can still send email and track positions using amateur radio:

Pat Winlink provides email over HF/VHF radio. Connect a $50 Digirig sound card interface between the Pi and any amateur radio, and CubeOS runs a complete Winlink client with a web-based mailbox. Peer-to-peer mode works without any infrastructure at all.

Direwolf turns the same setup into an APRS digipeater for automatic position reporting. Field team members with handheld radios appear on the CubeOS map with real-time GPS positions.

Amateur radio license required for normal operation. FCC §97.405 permits unlicensed use in life-threatening emergencies.

Multiple CubeOS nodes auto-discover each other and form an encrypted IPv6 mesh using Yggdrasil. Each node gets a stable cryptographic address. The mesh runs as an overlay on top of any network mode — even OFFLINE mode, where nodes communicate directly over WiFi.

The mesh enables distributed deployments: a base camp CubeOS shares its internet connection, GPS time, and satellite uplink with field nodes that only have line-of-sight WiFi links between them.

Requires a USB WiFi adapter (~$15) per node for the radio mesh layer. The built-in WiFi continues serving as the client access point.

Plug an HDMI display into the secondary port and CubeOS shows a full-screen browser pointed at any internal URL — the dashboard, Grafana metrics, offline maps, or a custom page. The primary HDMI port stays as a Linux console. Configure the display URL, page rotation, and on/off schedule from the dashboard settings. Perfect for base camp status boards, emergency operations centres, or digital signage.

Install self-hosted apps instantly. CubeOS is compatible with the CasaOS app ecosystem — over 800 apps across 15+ community-maintained stores including BigBearCasaOS (200+ apps), LinuxServer AppStore (100+ apps), and more. Apps are automatically checked for ARM64 architecture compatibility. Every install is protected by FlowEngine's transactional rollback — if anything fails, the system cleans up after itself.

Every app install, update, and removal runs as a saga — a sequence of steps where each one has a corresponding compensation (undo) action. If step 8 of 15 fails, FlowEngine automatically rolls back steps 7 through 1 in reverse order: removes the Docker stack, deletes the compose file, releases the allocated port, cleans up DNS entries, and removes directories. Zero orphaned resources, every time.

This matters because real-world installs fail. The SD card runs out of space mid-pull. The Pi loses power during deployment. The image doesn't exist for ARM64. Every other lightweight platform (CasaOS, Portainer, Coolify) leaves you with half-deployed stacks, phantom DNS entries, and leaked port allocations that you clean up manually. CubeOS treats app lifecycle as a transaction — it either completes fully or rolls back completely.

FlowEngine also provides crash recovery. If CubeOS reboots mid-install, the workflow resumes from the last completed step on next startup. Progress is tracked via Server-Sent Events and visible in the dashboard in real time.

The HAL is a privileged Go microservice running on each node that solves three problems Docker Swarm ignores:

1. Automatic hardware discovery and Swarm label management. The HAL scans USB, PCIe, I2C, GPIO, and system buses on startup and on hotplug events (via udev). It translates what it finds into Docker Swarm node labels through the Docker API — automatically. Plug a Coral TPU into Node 2 and the label hw.usb.coral-tpu=true appears. Unplug it, the label disappears. Swarm services with hardware constraints (--constraint 'node.labels.hw.usb.coral-tpu==true') automatically reschedule to follow the hardware. No SSH, no manual labels, no human memory required.

2. Network-transparent device access. Low-bandwidth devices (serial radios, GPS receivers, sensors, satellite modems, GPIO, I2C) are exposed as REST API endpoints that any container on any node can call over the network. A Meshtastic gateway container running on Node 1 can read the GPS position from a receiver plugged into Node 3 — it's just an HTTP call to http://node3.cubeos.cube:6005/api/v1/gps/position. The container doesn't know or care which node the hardware is on.

3. Semantic device APIs instead of raw passthrough. Containers don't get raw /dev/ttyUSB0 access. They get purpose-built endpoints: POST /api/v1/devices/iridium/send, GET /api/v1/devices/meshtastic/nodes, POST /api/v1/gpio/write. The Go drivers handle protocol details. Containers stay unprivileged and secure.

The HAL recognises two classes of hardware and handles them differently:

The distinction is bandwidth. A serial modem at 9600 baud generates bytes per second — trivial over a 1Gbps LAN. A Coral TPU processing video frames at 30fps requires direct PCI/USB bus access. The HAL makes this distinction automatically and applies the right strategy for each device.

Hardware capabilities across all nodes:

Every component is designed to work without internet connectivity:

• Local Docker registry caches images for offline app installation
• Pi-hole provides DNS/DHCP without upstream connectivity
• GPS NTP server keeps accurate time without internet NTP pools
• All core services function in airplane mode
• Local AI via Ollama with ChromaDB RAG — no cloud API keys needed
• Radio communications (Winlink, APRS) work without any IP infrastructure

• WireGuard and OpenVPN client/server support
• Per-app Tor routing for selective anonymity
• Firewall management with NAT control

• Mount SMB/NFS shares as app volumes
• USB drive auto-detection and mounting
• Backup to local, network, or external storage

┌─────────────────────────────────────────────────────────────────────┐
│  Browser / Phone                                                    │
└────────────────────────────────┬────────────────────────────────────┘
                                 │ HTTPS (Nginx Proxy Manager)
┌────────────────────────────────▼────────────────────────────────────┐
│  Dashboard (Vue.js 3)          — Web UI, responsive, theme-aware    │
└────────────────────────────────┬────────────────────────────────────┘
                                 │ REST API
┌────────────────────────────────▼────────────────────────────────────┐
│  CubeOS API (Go)               — Auth, Swarm orchestration, apps    │
│                                  Power mgmt, MPTCP, SDR, mesh       │
└──────────────┬─────────────────┬────────────────────────────────────┘
               │                 │ Internal API
               │  ┌──────────────▼──────────────────────────────────┐
               │  │  HAL Service (Go, privileged)                    │
               │  │  80+ REST endpoints · Swagger UI · SSE streams   │
               │  │  Auto-discovery · Dynamic Swarm labels · udev    │
               │  │  GPS/NTP · Power profiles · SDR · Radio · Mesh   │
               │  └──────────────┬──────────────────────────────────┘
               │                 │
┌──────────────▼─────────────────▼────────────────────────────────────┐
│  Raspberry Pi / ARM64 SBC                                           │
│  GPIO · I2C · USB · Serial · WiFi · Bluetooth · NVMe · GPS · SDR   │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│  Dashboard — unified view of all nodes and devices                   │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────────┐
│  CubeOS API — aggregates HAL data from every node                    │
└──────┬──────────────────┬──────────────────┬───────────────────────┘
       │                  │                  │
┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐
│   Node 1    │    │   Node 2    │    │   Node 3    │
│   HAL API   │◄──►│   HAL API   │◄──►│   HAL API   │
│             │LAN │             │LAN │             │
│ 🔌 Coral TPU│    │ 🔌 GPS      │    │ 🔌 LoRa     │
│ 🔌 Zigbee   │    │ 🔌 Iridium  │    │ 🔌 NVMe     │
│ 🔌 RTL-SDR  │    │ 🔌 UPS      │    │ 🔌 RTL-SDR  │
│             │    │             │    │             │
│  Docker     │    │  Docker     │    │  Docker     │
│  Engine     │    │  Engine     │    │  Engine     │
└─────────────┘    └─────────────┘    └─────────────┘

Any container on any node can access any device on any other node:
  GET http://node2.cubeos.cube:6005/api/v1/gps/position    ← from Node 1
  POST http://node2.cubeos.cube:6005/api/v1/iridium/send   ← from Node 3

High-bandwidth devices (GPU, TPU) use Swarm label constraints instead:
  Frigate → auto-scheduled to Node 1 (hw.usb.coral-tpu=true)

Yggdrasil mesh connects nodes that lack wired LAN — WiFi-only field relay.

Design principles:

• Unprivileged by default — Only 3 services need host access (Pi-hole, NPM, HAL). Everything else runs in isolated Swarm stacks.
• Hardware is discovered, not configured — Plug a device in. The HAL sees it, labels the node, exposes the API. No manual setup.
• Two strategies for two classes — Low-bandwidth devices are network-transparent (REST API over LAN). High-bandwidth devices use co-location (Swarm labels + device passthrough).
• Swarm stays unmodified — No forked Docker, no custom scheduler. The HAL feeds Swarm information through standard node labels. Swarm's existing constraint-based scheduling does the rest.
• Backend-for-Frontend pattern — The Dashboard talks only to the API. The API talks to HAL. Security boundaries are enforced at every layer.

CubeOS is not a single product — it's a platform that adapts to different hardware and use cases through specialised editions. The core operating system remains the same; each edition adds configuration profiles, HAL drivers, and pre-configured app stacks for its target environment.

                              ┌──────────────┐
                              │   CubeOS     │
                              │    Core      │
                              │              │
                              │  Dashboard   │
                              │  API + HAL   │
                              │  Swarm       │
                              │  App Store   │
                              └──────┬───────┘
                                     │
         ┌───────────────┬───────────┼───────────┬───────────────┐
         │               │           │           │               │
┌────────▼────────┐ ┌────▼───────┐ ┌▼──────────┐│ ┌─────────────▼──┐
│  CubeOS-NAS     │ │ CubeOS-    │ │ CubeOS-   ││ │  CubeOS-Edge   │
│                 │ │ MeshSat    │ │ Field     ││ │                │
│  RAID / ZFS     │ │            │ │           ││ │  NVIDIA DGX    │
│  Encrypted      │ │  LoRa Mesh │ │  GPS/NTP  ││ │  GPU / AI      │
│  File Sharing   │ │  Iridium   │ │  SDR      ││ │  K3s Clusters  │
│  Backup         │ │  SOS       │ │  Winlink  ││ │  Verticals     │
│                 │ │  Offline   │ │  Solar    ││ │                │
└─────────────────┘ └────────────┘ │  Mesh     ││ └────────────────┘
                                   └───────────┘│
                                                │
                             Mission Profiles ◄─┘
                             (pre-configured app bundles)

Mission Profiles are pre-configured app bundles selectable at first boot or from the dashboard. Each profile installs the right combination of services for a specific deployment scenario:

Profiles are JSON manifests — zero engineering cost per profile, just curated install lists. Users can customise after selection.

Turn a Raspberry Pi 5 with an NVMe HAT into a proper NAS — with a web UI, RAID, encrypted folders, and Samba/NFS sharing.

CubeOS-NAS extends the core platform with storage management features that compete with dedicated NAS operating systems, while retaining CubeOS's unique advantages: offline operation, self-healing containers, and a $0 price tag with no artificial limits.

Planned capabilities:

Target hardware: Raspberry Pi 5 with NVMe HAT (Pimoroni, Geekworm, etc.), USB SATA adapters, or any ARM64 SBC with multiple storage interfaces. Supports 2GB+ RAM.

Status: Planning phase. RAID management and encrypted volumes are the priority features for the first release.

Bridge an entire LoRa mesh network to the Iridium satellite constellation. Send texts, GPS positions, and SOS alerts from anywhere on Earth — no cell towers required.

CubeOS-MeshSat turns a CubeOS node into a Meshtastic-to-Iridium satellite gateway. One Raspberry Pi with a Heltec LoRa radio and a RockBLOCK 9603 satellite modem becomes the bridge between a local mesh network and global satellite coverage.

Core data flow:

Mesh Node ──LoRa──▶ Heltec Radio ──USB/BLE──▶ CubeOS HAL ──▶ cubeos-meshsat
                                                                    │
                                              CubeOS HAL ◀── RockBLOCK 9603
                                                                    │
                                                           Iridium Satellite
                                                                    │
                                                       Ground Control Webhook

Planned capabilities:

Hardware requirements:

How it works: The HAL provides two new driver modules — meshtastic (LoRa mesh communication) and iridium (satellite SBD protocol). The cubeos-meshsat app runs as a standard unprivileged Docker container, consuming real-time mesh messages via SSE from the HAL and forwarding them through the Iridium modem. Messages are compressed into a custom binary format to fit within Iridium's 340-byte MO limit. The SOS system implements a full state machine (IDLE → SENDING → WAIT_ACK → CONFIRMED) with GPIO trigger support for physical panic buttons.

Target users: Expeditions, maritime operations, remote field research, search and rescue, disaster response, off-grid communities.

Status: Architecture complete. HAL driver specifications defined for both Meshtastic (USB + BLE transports) and Iridium (AT command protocol). Implementation follows a 5-phase plan: HAL Iridium driver → HAL Meshtastic driver (USB) → HAL Meshtastic driver (BLE) → Bridge core → Web UI.

The missing management plane for NVIDIA DGX Spark and ARM64 edge AI devices. Transform a €3,000 desktop AI supercomputer into a business-ready appliance — with a web console, vertical solution templates, and one-click deployment.

NVIDIA ships the DGX Spark (128 GB unified GPU memory, ARM64) with zero web-based management. No browser dashboard, no container management UI, no out-of-band recovery, no fleet orchestration. The only interfaces are SSH and a local-only GPU telemetry page. CubeOS-Edge fills this gap.

Planned capabilities:

Scaling model:

Architecture difference: CubeOS-Edge uses K3s instead of Docker Swarm for orchestration. While Swarm is ideal for single-node Raspberry Pi deployments (lightweight, simple, Docker-native), DGX Spark clusters require Kubernetes-level features: Layer 7 routing, GPU scheduling, distributed inference coordination, and multi-node storage. The CubeOS API backend, Vue.js dashboard, and HAL architecture remain the same — the HAL simply gains GPU-specific discovery (nvidia-smi, VRAM, CUDA capabilities) while the orchestration layer changes underneath.

Target hardware: NVIDIA DGX Spark, MSI EdgeXpert, Jetson AGX Orin, any ARM64 Linux device with NVIDIA GPU. Also applicable to future GB-series products and third-party OEM variants.

Business model: The management platform is open-source (Apache 2.0). Revenue comes from vertical solution templates, enterprise support contracts, and custom WebUI development.

Status: Executive summary and architecture complete. First target vertical: Greek regulatory compliance monitoring (FEK corpus, 1M documents, 70B LLM). Fork-ready from CubeOS core — requires stripping Pi-specific components and adapting the HAL for GPU hardware.

1. Download the latest image from Releases

2. Flash to SD card using Raspberry Pi Imager

3. Boot your Pi and connect to the CubeOS-Setup WiFi network

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

5. Complete the setup wizard

Default credentials: admin / admin (change on first login)

# Clone the core repositories
git clone https://github.com/cubeos-app/api.git
git clone https://github.com/cubeos-app/hal.git
git clone https://github.com/cubeos-app/dashboard.git
git clone https://github.com/cubeos-app/coreapps.git

# Backend development (Go)
cd api && go build ./cmd/cubeos-api/

# HAL development (Go)
cd hal && go build ./cmd/cubeos-hal/

# Frontend development (Vue.js)
cd dashboard && npm install && npm run dev

All repositories have GitLab CI/CD pipelines that auto-deploy to the Pi on push to main. The development workflow is laptop → GitLab → Pi — no manual intervention on the device.

• Docker Swarm orchestration with self-healing
• HAL with 80+ hardware REST endpoints
• CasaOS app store compatibility (800+ apps)
• WiFi access point with three network modes
• Local AI with Ollama + ChromaDB RAG
• GitLab CI/CD auto-deployment pipelines
• Complete Swagger/OpenAPI documentation
• FlowEngine — transactional app lifecycle with saga-based rollback and crash recovery
• Local Docker registry as single source of truth for all images
• System updater with one-click dashboard updates
• Backup and restore system (local, USB, NFS/SMB)
• Raspberry Pi Imager official listing
• First-boot setup wizard
• HAL dynamic Swarm node labels (auto-discovery → label management via Docker API)
• HAL udev hotplug monitoring (device add/remove → label update → service reschedule)
• HAL network-transparent device access (cross-node REST API for low-bandwidth devices)
• Dashboard hardware attachment UI (per-app device selection with one-click redeploy)
• Multi-node HAL aggregation (unified hardware inventory across cluster)
• Multi-node Swarm clustering
• Read-only root filesystem option

• GPS time sync — sub-microsecond PPS, Stratum 1 NTP serving all WiFi clients
• NTP distribution — offline-accurate time for TLS, logs, sensors, radio protocols
• Smart power management — 4 profiles (Performance → Critical), solar/battery-aware container load shedding
• MPTCP WAN bonding — aggregate WiFi + cellular + Ethernet, serverless/BYOS/managed modes
• SDR integration — RTL-SDR detection, per-dongle assignment, ADS-B/AIS/weather satellite/general SDR
• Radio communications — Pat Winlink (email over HF), Direwolf APRS (position tracking)
• Yggdrasil mesh — encrypted IPv6 overlay, auto-discovery, batman-adv radio layer
• Kiosk display — dual-HDMI (console + kiosk), URL presets, rotation, scheduled on/off
• Mission Profiles (pre-configured app bundles per deployment type)

• HAL Iridium driver (RockBLOCK AT commands, SBD protocol)
• HAL Meshtastic driver — USB serial transport
• HAL Meshtastic driver — BLE transport
• Mesh-to-satellite bridge core with message queue
• SOS beacon with state machine and GPIO trigger
• Web UI (mesh node map, message history, diagnostics)

• RAID management GUI (mdadm)
• Encrypted volumes (LUKS / gocryptfs)
• Samba/NFS file sharing with user management
• Scheduled backup engine
• Time Machine target support

• Fork core platform for DGX Spark / ARM64 GPU hardware
• K3s orchestration layer (replacing Swarm)
• nvidia-smi GPU monitoring integration
• Setup wizard with vertical selection
• First vertical template: Legal/Compliance AI pipeline

We welcome contributions of all kinds — code, documentation, bug reports, feature ideas, and app store packages.

• Report bugs → GitHub Issues
• Discuss ideas → GitHub Discussions
• Submit PRs → Any repository. See our Contributing Guide.

Whether you're running CubeOS on a Pi at home, deploying it on a research vessel, or building AI appliances for enterprise customers — you're part of the same community.

CubeOS is open source under the Apache 2.0 License.

You can use, modify, distribute, and build commercial products on CubeOS — with no royalties, no paywall, and no artificial feature limits. This is a permanent commitment, not a growth strategy.

Built for expeditions, emergencies, and everyone who wants hardware that just works — across every node.

_{CubeOS · Apache 2.0 · Forever free · Forever open}