ZimaOS Architecture · My Observation (October 2025)
This post provides a technical overview of the ZimaOS architecture, based on official IceWhale sources and community validation as of October 2025.
It’s designed to help users, contributors, and developers understand how the system is structured—from the hardware layer up to the application and monitoring stack.
Layer 1 > Hardware
- Optimized for x86-64 (Intel / AMD) platforms and Zima hardware (ZimaBoard, ZimaCube)
- No official ARM builds at this time (community experiments exist but are not core releases)
- Includes lm-sensors and IPMI for monitoring, plus custom drivers for fan curves, RGB and GPIO
- Realtek r8125 (2.5 GbE) and r8168 (1 / 2.5 GbE) bundled in the IceWhale kernel
Layer 2 > Linux Kernel & Base OS
- Buildroot-based GNU/Linux environment optimized for appliance stability and OTA updates
- IceWhale-patched kernel (custom 6.12.x series, with optional 6.6 and 6.1 branches)
- Full glibc userland (no BusyBox) compiled through Buildroot toolchain 2.41
- Includes core storage utilities:
mdadm,btrfs-progs, and optionalzfs-dkmssupport - ZFS can be enabled via
zpkg(current tool) or equivalent CLI steps
Layer 3 > ZimaOS Core Services
| Service | Function | Details |
|---|---|---|
| zima-service | Hardware abstraction (RAID, sensors, fans) | Go binary under systemd |
| zima-api | REST + WebSocket backend | Port 5200 internal, documentation in progress |
| zima-web | React + Vite dashboard UI | Served via Caddy (80 / 443) |
| zima-backup | rsync + BTRFS / ZFS snapshot scheduler | Configurable via UI and CLI |
Layer 4 > Docker Engine
- Docker 25.x with containerd 1.7+ for app orchestration
- Default network
zima_default(bridge/NAT) and macvlan profiles for direct LAN IP apps - Standard data paths:
/DATA/AppData/<app>/,/DATA/Media/,/DATA/Backups/,/DATA/System/(encrypted when enabled)
Layer 5 > App Manager & Compose Toolbox
- Installs curated and community apps from the IceWhale Store (and compatible mirrors)
- Generates validated
docker-compose.ymlfor each install - Supports port mapping, volume binds, environment variables, health checks, and auto-updates
- Accepts custom Compose YAML imports through GUI or CLI
Layer 6 > Storage & RAID
mdadmRAID 0 / 1 / 5 / 6 / 10 mounted under/media- Filesystems:
ext4(default),BTRFS(native snapshots),ZFS(DKMS module, manual enable) - Monitored via
smartctl,mdadm --detail --scan, andzima-servicepolling
Layer 7 > Networking & Access
- Caddy v2 reverse proxy with auto-HTTPS (Let’s Encrypt or self-signed)
- Local discovery through Avahi / mDNS (
zimaos.local) - Remote access: Tailscale (built-in), Cloudflare Tunnel (app), Zima Cloud (beta)
Layer 8 > Apps & Extensions
- Official apps: Plex, Jellyfin, Immich, Nextcloud, Home Assistant
- AI stack: Ollama, Open WebUI, FAISS + RAG pipelines, Streamlit interfaces
- Automation: n8n, Node-RED, Home Assistant
- All apps managed via App Manager GUI with Docker controls
Layer 9 > Monitoring & Telemetry
- Netdata embedded for real-time CPU, disk, RAID and temperature metrics
- CLI utilities:
glances,btop - Prometheus exporters:
node_exporter,smartctl_exporter,mdadm_exporter - Metrics flow through zima-api to zima-web for visualization
Summary
ZimaOS is a lightweight, Buildroot-based NAS operating system centered on Docker containers. Its layered design promotes modularity and reliability from hardware abstraction to application orchestration.
Verified Sources
