Architecture

AtomOS is a layered stack: physical hardware, a supported Linux distribution, virtualization (KVM/QEMU/libvirt), AtomOS daemons, C4 coordination, and the interfaces operators use daily (Electros, AtomOS GUI, and atomos-cli). Understanding those layers helps you choose install roles, segment networks, and reason about failure domains.

Layer model

Layer	Technologies and responsibility
Operations interface	Electros (fleet), AtomOS GUI (on-host, from 0.9), `atomos-cli`, HTTPS APIs on the host
Coordination	C4 — peer discovery, capacity advertisement, scheduling inputs
AtomOS services	Compute (VM lifecycle), Storage (vaults and volumes), Cluster (membership and coordination), Client (APIs and access), optional GUI
Virtualization	KVM, QEMU, libvirt; virtual NICs and disks; optional PCIe passthrough
Host OS	AlmaLinux or Rocky (compute/full/storage); Ubuntu/Debian (storage and atomosgui only)
Hardware	x86_64 CPU with hardware virtualization, memory, NICs, boot and data disks, optional GPUs

You can still use familiar Linux and libvirt tools (for example virsh) for host-side inspection when your runbook allows it. Product-supported lifecycle and multi-host flows go through AtomOS services, Electros, or the AtomOS GUI.

AtomOS service roles on the host

Install atomos-cli once, then deploy one or more roles:

Role	Primary services	Notes
compute	Compute, cluster-related client stack	No Elemento vault creation on this node
storage	Storage daemons and vault management	Serves volumes to compute nodes over the storage API
full	Compute + storage	Common for labs, PoC, and HCI-style nodes
atomosgui	On-host web UI	Electros-like experience locally; install after or with other roles

Service boundaries and ports are documented in the install reference (Application ports). Exact package names follow your distro and AtomOS release.

Portable pledges and specfiles

Scheduling is driven by specfiles: JSON pledges that describe required resources (CPU topology policy, memory, optional device constraints) without naming a destination host.

Concept	Meaning
Specfile	Portable workload description, versioned and shareable
Pledge	A submitted request derived from a specfile
Advertisement	What a host reports as available capacity and capabilities
Match	A scheduling decision that a given host can satisfy the pledge

Electros is the usual authoring and submission path for organization users. C4 uses discovery and advertisements from reachable hosts to inform placement. The same pledge can be re-submitted after maintenance or host loss if shared storage, networking, and your procedures support the outcome — C4 does not replace those dependencies.

Diagram: single-host (full role)

One machine runs the full stack: OS, KVM, compute, storage, cluster membership, and optional AtomOS GUI. Electros may manage the host as a registered target.

mermaid

flowchart TB
  subgraph single["Single physical host — full role"]
    subgraph mgmt["Management access"]
      ADM[Administrators]
      ES[Electros users]
    end
    subgraph ui["Interfaces"]
      E[Electros]
      GUI[AtomOS GUI optional]
      CLI[atomos-cli]
    end
    subgraph aos["AtomOS"]
      C4[C4 / cluster]
      COMP[Compute]
      STOR[Storage / vaults]
    end
    subgraph virt["Virtualization"]
      L[libvirt / QEMU / KVM]
    end
    subgraph os["Host OS"]
      LIN[AlmaLinux or Rocky 9]
    end
    ADM --> CLI
    ES --> E
    E -->|HTTPS target APIs| COMP
    E --> STOR
    GUI --> COMP
    GUI --> STOR
    CLI --> COMP
    CLI --> STOR
    C4 --> COMP
    C4 --> STOR
    COMP --> L
    STOR --> L
    L --> LIN
  end

Diagram: multi-host cluster

Several AtomOS hosts share a network where C4 can discover peers. Compute nodes run VMs; storage may be local to each node or concentrated on dedicated storage roles depending on your design.

mermaid

flowchart LR
  subgraph clients["Clients"]
    E[Electros]
  end
  subgraph net["Shared L2/L3 reachability"]
    H1["Host A — full or compute"]
    H2["Host B — full or compute"]
    H3["Host C — storage"]
  end
  E -->|Register and enable targets| H1
  E --> H2
  E --> H3
  H1 <-->|C4 discovery cluster ports| H2
  H1 <-->|C4 discovery cluster ports| H3
  H2 <-->|C4 discovery cluster ports| H3
  H1 --> VM1[Guests]
  H2 --> VM2[Guests]
  H3 --> VAULT[Vaults / volumes]
  H1 -.->|Storage API when configured| VAULT
  H2 -.->|Storage API when configured| VAULT

Firewall and port requirements for cluster, compute, and storage traffic are listed in the install reference. Design management networks so Electros and administrators can reach each target IP you register.

Diagram: separated compute and storage

Scale hypervisor and vault tiers independently. Compute nodes do not hold Elemento vaults; storage nodes export volumes to compute over AtomOS storage services.

mermaid

flowchart TB
  subgraph electros["Electros"]
    EC[Control plane]
  end
  subgraph compute_tier["Compute tier"]
    C1[Compute node 1]
    C2[Compute node 2]
  end
  subgraph storage_tier["Storage tier"]
    S1[Storage node 1]
    S2[Storage node 2]
  end
  EC --> C1
  EC --> C2
  EC --> S1
  EC --> S2
  C1 <-->|Cluster / C4| C2
  C1 -->|Storage service ports| S1
  C2 -->|Storage service ports| S1
  C2 -->|Storage service ports| S2
  C1 --> G1[VMs]
  C2 --> G2[VMs]
  S1 --> D1[(Vault backends)]
  S2 --> D2[(Vault backends)]

Use Planning and Storage architecture when you split tiers. Ubuntu or Debian hosts fit the storage tier only in supported matrices.

Diagram: Electros interaction (conceptual)

This diagram shows relationships, not a wire-level protocol specification. Electros talks to each registered target over HTTPS using host certificates you trust. C4 operates among AtomOS hosts on the network paths you provide.

mermaid

sequenceDiagram
  participant Op as Operator
  participant El as Electros
  participant T as AtomOS target
  participant Peers as Other AtomOS hosts
  Op->>El: Define scenario / enable target
  Op->>El: Submit VM pledge from specfile
  El->>T: HTTPS API — capacity and operations
  T->>Peers: C4 discovery and advertisements
  Peers->>T: Peer advertisements
  Note over El,T: Scheduling uses reachable hosts and pledges
  El->>T: Provision or control VM
  T->>T: libvirt / QEMU / KVM

Registration and trust steps:

Add the host under Connections → Targets in Electros.
Compare TLS fingerprints with atomos-cli --show-fingerprint on the host.
Enable the target under Active Connections for your session or scenario.

See VMs & Electros and Networking & certificates.

AtomOS GUI (from 0.9)

The atomosgui role installs an on-host management UI with an Electros-like workflow for local users. It complements — does not replace — organization-wide Electros:

Aspect	Electros	AtomOS GUI
Scope	Organization, multiple targets and clouds	Single host
Users	Electros organization accounts	Local users (`atomos-cli -mu`) and groups
Trust	Target registration and fingerprint approval	Host-local authentication

Install with sudo atomos-cli --install atomosgui on-prem (or cloud on supported CSP instances). GUI service ports appear in the install reference.

Virtualization and devices

Guests run as KVM domains under libvirt. Virtual disks and NICs attach through AtomOS storage and network configuration. GPU and PCIe passthrough require IOMMU, suitable groups, and guest planning — see GPU / PCI passthrough. Passthrough guests often constrain live migration options.

Trust and security boundaries

Boundary	Mechanism
Electros ↔ host	HTTPS, certificate fingerprint verification
Host ↔ host	Peer certificate pinning for service calls (`atomos-cli --get-certificate`); cluster HMAC when configured — see Security
Tenant ↔ tenant	VM isolation, networks, vault access, Electros permissions
User ↔ host OS	Standard Linux authentication; `atomos-cli` install requires root

Deep dive: Multi-tenancy, security, and isolation.

Failure domains (architectural view)

Component	If it fails	Design note
Single full node	Compute and local vaults on that box are affected	Backups and spare capacity per your RTO/RPO
Compute node	VMs on that hypervisor are affected	Redistribute pledges only where storage and network allow
Storage node	Volume availability depends on backend redundancy	Use mdadm, ZFS, GlusterFS, or external backends as appropriate
Electros	Fleet UI and orchestration path affected; hosts may keep running	Operational runbooks for direct host access
Network partition	Discovery and storage paths may split	Segment management, cluster, and storage networks deliberately

Availability patterns: Availability & recovery.

Next steps

Core concepts (C4) — discovery, scheduling, and authorization
Hardware & platforms — validate CPU, IOMMU, and OS choice
Install with atomos-cli — deploy roles on a prepared host

Architecture ​

Layer model ​

AtomOS service roles on the host ​

Portable pledges and specfiles ​

Diagram: single-host (full role) ​

Diagram: multi-host cluster ​

Diagram: separated compute and storage ​

Diagram: Electros interaction (conceptual) ​

AtomOS GUI (from 0.9) ​

Virtualization and devices ​

Trust and security boundaries ​

Failure domains (architectural view) ​

Next steps ​

Architecture

Layer model

AtomOS service roles on the host

Portable pledges and specfiles

Diagram: single-host (full role)

Diagram: multi-host cluster

Diagram: separated compute and storage

Diagram: Electros interaction (conceptual)

AtomOS GUI (from 0.9)

Virtualization and devices

Trust and security boundaries

Failure domains (architectural view)

Next steps