What is AtomOS

AtomOS is Elemento's Linux-native hypervisor framework. It adds managed compute, storage, clustering, and local management services on top of a supported host operating system, using KVM, QEMU, and libvirt for virtualization. You install and operate AtomOS with atomos-cli (bootstrap script: get-atomos.sh from repo.elemento.cloud).

AtomOS is not a Linux distribution. You do not replace AlmaLinux, Rocky Linux, or another supported distro with a separate AtomOS ISO. You start from a clean, compatible OS install, then use atomos-cli to deploy the AtomOS service stack on that host.

Scope of this guide

This page orients you to the product. For layer-by-layer detail, see Architecture. For capacity and platforms, see Hardware. For deployment design, see Planning.

What AtomOS provides

Capability	Detail
Virtualization	Hardware-assisted KVM guests via QEMU; standard libvirt tooling (for example virsh) remains available on the host
Install roles	compute, storage, full (both), and atomosgui (on-host management UI from AtomOS 0.9)
Multi-host coordination	C4 for discovery and scheduling among reachable hosts — see Core concepts (C4)
Fleet control plane	Electros for organization-wide targets, VMs, networks, storage, and scenarios
Portable workloads	Specfiles (JSON pledges) describe resource needs without binding a VM to one physical server

AtomOS runs on bare metal and on provider instances where the platform exposes usable hardware virtualization (including nested virtualization on some public clouds). Validate the exact offering before production.

What AtomOS is not

Misconception	Reality
A replacement distro	A framework of daemons and packages on a supported Linux base
A mandatory central controller for every host	Hosts can discover peer capacity on the network via C4; Electros adds organization-level authorization and operations
Automatic high availability	Discovery and portable pledges help place and re-place workloads; HA still requires your topology, storage, networking, and procedures — see Availability & recovery
The same product as Cockpit	Cockpit is the generic host OS web console (port 9090). It does not replace AtomOS services, Electros, or the AtomOS GUI

Management surfaces: Electros, AtomOS GUI, and Cockpit

Operators interact with AtomOS through several layers. Keep their responsibilities separate:

Surface	Scope	Typical use
Electros	Organization-wide control plane	Register targets, enable Active Connections, create VMs from specfiles, manage networks and storage across hosts and clouds
AtomOS GUI (atomosgui role, from 0.9)	On-host, Electros-like UI	Local user provisioning and host-scoped operations when Electros is not in the path
atomos-cli	Host installation and administration	Install roles, bridges, certificates, vaults, service control, fingerprints, health checks
Cockpit	Host OS administration	Distro packages, systemd, storage at the OS level — complementary, not the AtomOS API

Authoritative CLI reference

Flag names and service ports can change between releases. On the installed host, run atomos-cli --help. For ports and common sequences, see Install & CLI reference.

Self-service operations vs infrastructure administration

Historically, every VM request flowed through a sysadmin. AtomOS supports two deliberate paths:

Self-service operations — Authenticated users with the right organization permissions (in Electros) or local AtomOS GUI groups request and run capacity themselves: create VMs, attach networks and volumes, and perform allowed lifecycle actions within policy you define.

Infrastructure administration — Platform teams retain exclusive control over host install, networking bridges, vault layout, certificate trust, firewall rules, OS patching, capacity limits, and break-glass maintenance. Admins decide who may use self-service and what quotas or templates apply.

Permissions are layered

Electros organization roles govern who can register targets, enable scenarios, and create cloud resources. AtomOS GUI local groups (storage, compute, admin) govern on-host actions. Neither replaces host root/sudo for atomos-cli install and deep maintenance. See Multi-tenancy, security, and isolation and Install — local users (AtomOS GUI).

C4 in brief

C4 is Elemento's protocol for host discovery, resource advertisement, and scheduling among AtomOS nodes that can reach each other on the network. When Electros (or another client) submits a VM pledge from a specfile, C4 helps match requirements to hosts that advertise suitable capacity.

C4 does not by itself guarantee failover or uptime. It makes capacity visible and matchable; your storage, network, and operational design determine what happens when a host fails. Details: Core concepts (C4).

Specfiles and portable pledges

A specfile is a portable JSON description of what a workload needs: vCPU count and allocation policy, memory, optional device constraints, and related fields — not the name of a specific host. Templates are documented, redistributable specfiles you can standardize for teams.

Workflow at a high level:

1. An operator or user defines or selects a specfile (often via Electros).
2. The pledge is submitted to the environment.
3. C4 discovery and scheduling consider reachable hosts that advertise matching capacity.
4. Provisioning runs on the selected host.

If a host becomes unavailable, the same pledge can be submitted again so scheduling can consider other reachable hosts that still satisfy the constraints — provided storage and networking support that outcome.

Terminology

See Glossary for definitions of pledge, specfile, target, vault, and related terms.

Core components

flowchart TB
  subgraph control["Control and operations"]
    E[Electros]
    G[AtomOS GUI]
    CLI[atomos-cli]
  end
  subgraph coord["Coordination"]
    C4[C4 discovery and scheduling]
  end
  subgraph atomos["AtomOS services"]
    COMP[Compute]
    STOR[Storage]
    CLU[Cluster]
  end
  subgraph virt["Virtualization"]
    KV[KVM / QEMU / libvirt]
  end
  subgraph host["Host OS"]
    OS[Supported Linux distro]
  end
  E --> C4
  G --> COMP
  G --> STOR
  CLI --> COMP
  CLI --> STOR
  C4 --> COMP
  C4 --> STOR
  COMP --> KV
  STOR --> KV
  CLU --> COMP
  KV --> OS

Component	Responsibility
AtomOS services	Run VMs, vaults, cluster membership, client APIs, and optional on-host GUI
C4	Discovery, capacity advertisement, and scheduling among peers
Electros	Organization targets, authorization, and multi-host/cloud operations
Linux / KVM / QEMU / libvirt	Kernel virtualization, guest runtime, and familiar admin tools

Install roles

Choose a role before install; changing topology later may require redeploying services or moving storage.

Role	Installs	Typical use
compute	Compute and cluster client stack	Hypervisor nodes without local Elemento vaults
storage	Storage services	Dedicated vault hosts; required on Ubuntu/Debian
full	Compute + storage	Single-node or hyperconverged (HCI) footprints
atomosgui	On-host management UI	Local self-service and admin UI (0.9+)

Commands and platform notes: Install with atomos-cli.

Where to go next

1. Architecture — layers, diagrams, and Electros interaction
2. Core concepts (C4) — discovery, trust, and scheduling
3. Hardware & platforms — compatibility and sizing
4. Planning — topologies, networks, and checklists
5. Install with atomos-cli — bootstrap and role install
6. Glossary — shared vocabulary