Use cases and topologies

Actionable deployment patterns for AtomOS with Electros. Each pattern lists architecture, dependencies, benefits, and operational limitations. This page does not specify capacity numbers, SLAs, or license counts — size with Planning and Hardware & platforms.

Capability status varies by release: Feature availability.

---

How to read these patterns

Column	Meaning
Use case	Business or technical driver
Architecture	Roles, networks, control plane
Dependencies	What must work first
Benefits	Why teams choose this shape
Operational limitations	What this pattern does not solve by itself

Electros is the fleet control plane for most patterns. AtomOS GUI (atomosgui) suits single-site local ops from the 0.9 milestone onward.

---

Small organization (one to few hosts)

Use case: Consolidate a handful of servers into VMs with minimal moving parts — branch office, small IT team, or first production pilot.

Architecture:

• One full node (compute + storage on same host), or compute plus a dedicated storage node when you outgrow local disks.
• Single br0 (or access VLAN) for guests; management on the same or separate NIC per Networking.
• Electros SaaS or self-hosted for VM lifecycle.

Dependencies: Outbound HTTPS to Elemento endpoints; TLS trust from 0.9; backup agent or file-level backup of /mnt vaults (Backup).

Benefits: Low hardware count; simple Electros target list; fast time to first VM (Quick start).

Operational limitations: Single full node is a single point of failure for compute and local vaults. Multi-host ≠ HA (Availability & recovery). Plan maintenance windows and backups explicitly.

---

Enterprise private virtualization

Use case: On-prem private cloud for many VMs, distinct admin teams, and integration with existing LAN security zones.

Architecture:

• Multiple compute nodes behind Electros Active Connections.
• One or more storage nodes with POSIX vaults on RAID, ZFS, or shared storage backends validated in your lab.
• Management network for SSH/Electros HTTPS; guest br0 (or VLANs via VLANs) per zone.
• Optional atomosgui on edge nodes for local break-glass.

Dependencies: Consistent TLS SANs and fingerprint trust; peer --get-certificate where compute talks to storage; ELEMENTO_CLUSTER_SECRET aligned on cluster peers when configured (Install reference).

Benefits: Central governance in Electros; horizontal compute growth; storage tier can scale independently when backends support shared visibility.

Operational limitations: Automatic failover SLA and unattended host-death recovery are unknown — requires verification for your release (Feature availability). Live migration requires shared/eligible storage and compatible guests (Migration). DLB is preview/beta — do not assume it replaces runbooks.

---

MSP multi-customer

Use case: Service provider runs infrastructure for several end customers with isolation and delegated administration.

Architecture:

• Pool of compute (and optionally storage) hosts per region or per customer tier.
• Electros organizations, scenarios, and permissions to separate customer visibility (Electros docs authoritative for RBAC).
• Network isolation via VLANs, separate bridges, or upstream firewalls — not implied by AtomOS install alone.

Dependencies: Strong certificate and target naming discipline; documented IP plans; backup and elemento-bin retention per customer policy (Storage).

Benefits: One operator stack; repeatable atomos-cli --install compute on-prem; centralized VM templates via Electros.

Operational limitations: Tenant isolation is a system design outcome (network + Electros permissions + storage boundaries). AtomOS does not replace contractual SLAs or compliance attestations you define with customers.

---

Private AI / GPU

Use case: Training or inference VMs with GPU passthrough or dedicated accelerators on-prem.

Architecture:

• compute nodes with IOMMU-enabled hardware (Hardware, GPU passthrough).
• Fast storage vaults (local NVMe or low-latency SAN) for datasets and checkpoints.
• Management network separate from high-throughput guest NICs when possible.

Dependencies: --pci-list validation; guest driver install inside VMs; Electros specs that request passthrough devices.

Benefits: Data residency; predictable hardware; integration with existing LAN storage.

Operational limitations: Passthrough blocks live migration for affected guests. GPU partitioning (shared vGPU/MIG-style) is unknown — requires verification (Feature availability). Power and cooling are site constraints — not documented here.

---

Edge and branch

Use case: Workloads run close to users or equipment; central Electros management from HQ.

Architecture:

• full or compute at the edge; storage local or remote over VPN/MPLS to a central storage node.
• atomosgui for local operators when Electros path is slow or restricted.
• cloud install type when edge nodes are small CSP instances.

Dependencies: Reliable path for Electros HTTPS (0.9 certs); bandwidth for template sync and updates; offline update plan if link fails.

Benefits: Low latency to local users; unified VM policy from Electros.

Operational limitations: Remote vaults over WAN increase latency and split-brain risk during partitions — design storage visibility and maintenance procedures accordingly. Edge HA is not automatic.

---

Separated compute and storage

Use case: Scale CPU independently from capacity-heavy storage; align with existing SAN or filer investments.

Architecture:

• compute fleet (no local vaults or minimal cache only).
• storage cluster with vaults on shared backends (iSCSI, NFS, Gluster, etc. — validate each).
• Storage network isolated from guest br0 when security policy requires.

Dependencies: Network paths open between compute and storage service ports (Reference); peer certificate pinning and aligned cluster secrets where used (Security); backend-supported mount paths for every vault.

Benefits: Independent refresh cycles for compute vs disk shelves; clearer blast radius for storage maintenance.

Operational limitations: Backend outage affects all dependent VMs. Backend-specific HA (e.g. array replication) is vendor and design territory — AtomOS documents vault lifecycle, not array firmware SLAs.

---

Multi-node cluster (coordination focus)

Use case: Several AtomOS hosts discover each other via C4, share cluster services, and accept pledges from Electros.

Architecture:

• Multiple compute or full nodes on a common L3/L2 fabric.
• Optional dedicated storage tier.
• Cluster UDP/TCP paths among peers; Electros HTTPS to each registered target.

flowchart TB
  E[Electros]
  C1[Compute A]
  C2[Compute B]
  S[Storage]
  E --> C1
  E --> C2
  C1 <-->|C4 / cluster| C2
  C1 --> S
  C2 --> S

Dependencies: C4 reachability; consistent ELEMENTO_CLUSTER_SECRET when used; certificate pinning between peers.

Benefits: Pool capacity; reschedule pledges to surviving hosts when storage and constraints allow.

Operational limitations: See Availability & recovery — registering multiple targets is not a verified automatic failover product. Validate failure scenarios in staging.

---

Choosing a pattern

If you need…	Start with…
Fastest first VM	Quick start, single full
Growth without redesign	Enterprise or separated compute/storage
Customer isolation	MSP + VLAN/network design + Electros RBAC
GPUs	Private AI topology + GPU guide
Proof of multi-host scheduling	Multi-node + C4 docs; prove storage visibility before claiming HA

Related: Architecture, Planning, Security.