Compatibility matrix

What HiveCast is tested on, what is expected to work, and what is explicitly unsupported. Honest framing.

Operating system

OS	Status	Install path	Notes
Ubuntu 22.04 LTS (amd64)	tested	`.deb`	Primary CI target
Ubuntu 22.04 LTS (arm64)	tested	`.deb`	arm64 deb is built
Ubuntu 24.04 LTS (amd64/arm64)	expected to work	`.deb`	Same systemd shape
Debian 12 (Bookworm)	expected to work	`.deb`	Same dpkg lineage
RHEL 9 / Fedora 40	not tested	source-checkout	systemd path should work; no `.rpm` packaging
Arch Linux	not tested	source-checkout	systemd path should work
macOS 13+ (Apple Silicon / Intel)	partial	source-checkout	Wrapper runs; launchd integration is target state
Windows 10 / 11 (x64)	partial	source-checkout	Wrapper runs (Node + bash via Git Bash / WSL); Windows Service integration is target state
Container (any base)	tested	`.deb` or source-checkout	Postinst auto-detects and binds `0.0.0.0`

The .deb is the supported path for production-ish use. Source-checkout works on every platform Node 20+ supports.

Node.js

Version	Status	Notes
20.x	tested	Used by `.deb` (vendored Node 20)
22.x	expected to work	Same major-version compat
18.x or older	not supported	Some bundled packages use newer features

The .deb ships its own Node at /opt/hivecast/node/bin/node, so the system Node version doesn't matter for .deb installs. For source-checkout, install Node 20+ via your distro's Node setup.

NATS

Version	Status	Notes
2.10.x	tested	Bundled with hivecast
2.11.x	expected to work	Same config + JetStream API
Older NATS	not supported	JetStream features not present

hivecast install drops the bundled NATS binary (per arch). External NATS (transport.nats.mode: 'external', custom url) is supported but you're responsible for making sure it's a recent JetStream-capable version.

Browsers (for the bundled webapps)

Browser	Status
Chrome / Chromium 120+	tested
Firefox 120+	tested
Safari 17+	expected to work
Edge 120+	expected to work (Chromium-based)
Mobile browsers	not tested
IE / legacy	not supported

The bundled webapps use modern web platform features (custom elements, modern ESM, WebSocket). Older browsers will fail.

CPU architectures

arch	Status	`.deb` arch
x86_64 / amd64	tested	`amd64`
arm64	tested	`arm64`
ppc64le, riscv64	not supported	none built

scripts/build-deb-installer.js:403-407 enumerates supported archs:

function debArchFor(nodeArch) {
  if (nodeArch === 'x64') return 'amd64';
  if (nodeArch === 'arm64') return 'arm64';
  throw new Error(`unsupported architecture for deb package: ${nodeArch}`);
}

Containers / orchestration

Platform	Status	Notes
Docker (single container)	tested	Per `projects/matrix-worker/`
Docker Compose (multiple workers)	tested	`docker compose up -d --scale worker=3`
Kubernetes	expected to work	No specific Helm chart yet
Podman	expected to work	Same OCI image format

Container detection in postinst handles the bind-host switch automatically.

Multi-Host on one machine

Pattern	Status	Notes
Two `hivecast` Hosts on one machine, different `--home` and `--http-port`	supported	Each gets its own NATS sibling
Two Hosts sharing one NATS	not supported	Each Host's wrapper expects its own NATS
Multiple browser sessions per Host	supported	Browser tabs each connect independently

The two-runtime dev topology (matrix-web as platform shell + matrix-edge as Device shell on the SAME Host) is supported and is the recommended dev pattern. Per CLAUDE.md's "Two-Runtime Dev Topology" section.

Filesystem requirements

~500 MB for the bundled package set after install
Additional space for runtime logs (rotated/capped at 2 GB by journald .deb)
POSIX permissions (mode bits, ownership)
Atomic-rename support (fs.renameSync) for safe writes

POSIX-incompatible filesystems (FAT32 on Linux, etc) are not supported. NTFS via WSL2 works.

TLS / production deployment

The Host does not terminate TLS. For TLS, run a reverse proxy (nginx, Caddy, Traefik) in front. hivecast.ai itself does this.

Reverse proxy	Notes
nginx	Tested
Caddy	Tested
Traefik	Expected to work
HAProxy	Expected to work

The proxy must:

terminate TLS
forward HTTP and WebSocket upgrades
preserve X-Forwarded-Proto, X-Forwarded-Host

Cookie domain must match the proxy's external host for session-cookie-based auth (auth.mode: 'public-session').

What's NOT supported

Running multiple Hosts under the same <host-home> (state corruption)
Running the Host as root for routine operation (works, but security-bad)
Using a non-JetStream NATS broker (some features depend on JetStream)
Sharing <host-home> over NFS / SMB (filesystem semantics around lock/atomic-rename are unreliable)
Running on Windows without WSL or Git Bash (the .mjs wrappers need bash for some operator scripts)

Versioning

HiveCast versions follow semver, but the public API surface is small (the CLI). Internal package versions move independently. Per CLAUDE.md Rule 9:

Additive-only schema evolution — never remove fields, only add optional ones

So old runtime records and config files remain readable across versions; new fields are added with sensible defaults.

Compatibility matrix ​

Operating system ​

Node.js ​

NATS ​

Browsers (for the bundled webapps) ​

CPU architectures ​

Containers / orchestration ​

Multi-Host on one machine ​

Filesystem requirements ​

TLS / production deployment ​

What's NOT supported ​

Versioning ​

See also ​