Core concepts (C4)

C4 is Elemento's protocol for node discovery, resource advertisement, and distributed scheduling among AtomOS hosts. Clients (typically Electros) submit VM requests as pledges derived from specfiles; reachable hosts advertise what they can offer; scheduling matches requests to suitable capacity.

C4 answers: which AtomOS nodes are visible on the network, what can they run, and where should this pledge land? It does not replace storage design, network redundancy, or runbooks for host failure.

Discovery is not high availability

Peer discovery and portable pledges help Electros and C4 find and use alternate hosts. That is not the same as guaranteed automatic failover, zero downtime, or a certified HA SLA. Plan storage replication, network paths, and recovery steps explicitly — see Availability & recovery.

Responsibilities at a glance

Area	C4 and AtomOS hosts	Electros and operators
Discovery	Hosts on reachable networks advertise cluster membership and capacity	Registers targets, enables Active Connections, defines scenarios
Advertisement	Compute/storage services expose schedulable resources	Presents inventory and health in the UI
Scheduling	Matches pledge constraints to advertised capacity among peers	Submits pledges, may allow automatic or manual host choice
Authorization	TLS on host APIs; optional allow/ban lists via atomos-cli	Organization roles; target trust and fingerprint approval
Provisioning	libvirt/QEMU execution on selected host	Workflow, templates, and policy

Host discovery

When compute and cluster-related services are running, AtomOS hosts participate in peer discovery on the networks you configure. Hosts that can reach each other can exchange C4 discovery traffic (cluster service ports in the install reference).

Practical assumptions:

• Hosts share L2 or routed L3 reachability for cluster UDP/TCP ports you open.
• Firewalls allow discovery and service traffic between peers — not only between Electros and one host.
• Multiple subnets are supported when routing and firewall policy permit peer paths; do not assume discovery crosses arbitrary ACLs without testing.

Discovery makes capacity visible. It does not automatically migrate running VMs or rebuild storage.

Resource advertisement

Each participating host advertises what it can contribute: compute capacity (CPU and memory policies), storage attachment when the storage or full role is present, and cluster membership state. Advertisements feed scheduling when a pledge arrives.

Factors that affect whether a host is eligible for a pledge include:

• Installed role (compute-only nodes do not satisfy storage-local pledges that require local vaults on the same box unless your architecture places volumes remotely).
• Resource limits already consumed by running guests.
• Specfile constraints (CPU topology, memory, optional device requirements such as passthrough — see GPU / PCI passthrough).
• Reachability from the client and from peer services at request time.

Use atomos-cli --info and atomos-cli --healthcheck on hosts for operational visibility; Electros surfaces target state after registration.

Scheduling

Scheduling connects a pledge to a destination host:

flowchart LR
  A[Specfile / pledge] --> B{Constraints}
  B --> C[Reachable hosts]
  C --> D[Advertised capacity]
  D --> E{Eligible hosts}
  E --> F[Selected host]
  F --> G[Provisioning on libvirt/KVM]

Typical flow:

1. An AtomOS host starts compute (and cluster-related) services and joins discovery on the network.
2. Electros reaches hosts configured as targets in the organization.
3. An operator or user submits a VM request; the pledge carries CPU, memory, and related fields from the specfile.
4. C4 discovery and scheduling logic considers hosts that are reachable and eligible.
5. The system selects a destination; provisioning begins on that host.

Electros may offer automatic host selection when policy allows, or require an explicit choice. Behavior is governed by Electros scenario configuration and what the hosts advertise — not by C4 alone.

Trust and authorization

Two distinct ideas often get conflated:

Network discovery (C4)

Hosts discover peers and advertisements on the data paths you provide. Protect cluster and service networks with firewall zones, VLANs, and monitoring appropriate to your threat model.

Electros target registration (organization authorization)

A discovered host is not automatically usable in your Electros organization until an admin:

1. Adds the host under Connections → Targets.
2. Verifies the TLS certificate fingerprint (compare Electros with atomos-cli --show-fingerprint on the host).
3. Enables the target under Active Connections (or the relevant scenario).

Electros then communicates with the host over HTTPS. From AtomOS 0.9, host services expect HTTPS certificates you generate and trust — see Networking & certificates.

Host-to-host trust

Peers that invoke each other's compute or storage APIs must mutually trust certificates. Use atomos-cli --get-certificate as documented in Networking & certificates (Trust between AtomOS hosts).

Local API access controls

atomos-cli supports allow and ban lists for client UIDs on the host. Use these when hardening edge access; they complement Electros organization permissions rather than replacing them.

Network assumptions

Traffic type	Purpose	Documentation
Electros → target	HTTPS management and VM operations	VMs & Electros, Networking
Host ↔ host	Cluster discovery, compute, storage APIs	Install reference — application ports
Administrators → host	SSH, optional Cockpit (9090), AtomOS GUI (7780/7781)	Install reference — access services
Guests	Bridge br0 (or your chosen bridge)	Networking

Outbound internet during install and updates must reach distro repositories and Elemento endpoints (idp.elemento.cloud, repo.elemento.cloud, portal.elemento.cloud) — see Install reference.

Validate before production

Run atomos-cli --verify-network on cloud instances where provider routing (including IPv6 default routes) can break installs. See Install.

Service dependencies

C4 coordination sits alongside AtomOS daemons. A simplified dependency view:

flowchart TB
  subgraph electros_path["Electros path"]
    EL[Electros]
  end
  subgraph host["AtomOS host"]
    CL[Cluster / C4]
    CO[Compute]
    ST[Storage optional]
    LV[libvirt / KVM]
  end
  EL -->|HTTPS| CO
  EL -->|HTTPS| ST
  CL --> CO
  CO --> LV
  ST --> CO
  CL <-->|Discovery ports| CL

• Compute depends on working virtualization (KVM modules, libvirt).
• Storage depends on configured vault backends and mounts — Storage architecture.
• Cluster depends on network reachability between peers.
• Electros operations depend on target registration, trust, and enabled connections.

If cluster services are stopped or firewalled, discovery and multi-host scheduling inputs degrade even when single-host virsh might still work.

Portable pledges and host failure

Specfiles describe what is needed, not which host must run the workload. When a host fails or is drained:

• Running guests on that host stop unless you have live migration or external orchestration in place.
• A stored pledge or template can be re-submitted so scheduling considers other reachable hosts that satisfy constraints.

Re-placement succeeds only when:

• Volumes are reachable from the new host (shared storage, network storage, or restored backups).
• Networks exist on the destination.
• Constraints (CPU features, passthrough devices) are still satisfiable.

C4 facilitates matching; your storage and network architecture determine whether failover is practical.

Failure and partition considerations

Scenario	Typical effect	Mitigation direction
Single host down	Guests on that host unavailable	Spare capacity; backups; maintenance windows
Storage node down	Volume I/O depends on backend redundancy	RAID/ZFS/GlusterFS/Quobyte design; Backup & recovery
Network partition	Split discovery or split storage paths	Separate management, cluster, and storage networks; monitoring
Electros unavailable	No fleet UI; hosts may continue running VMs	Break-glass SSH and atomos-cli procedures
Certificate expiry or mismatch	HTTPS failures to targets	--generate-cert, fingerprint re-trust, Networking
Mis-registered target	Operations against wrong host	Fingerprint verification before trust

Relationship to clustering and migration

Multi-host continuity combines C4 visibility with cluster membership, storage layout, and procedures documented under Availability & recovery and Migration & import. Live migration has additional CPU, storage, and device constraints.

Checklist before relying on C4 in production

• [ ] Cluster, compute, and storage ports opened per install reference between all peers that should discover each other
• [ ] Electros targets registered, fingerprints verified, connections enabled
• [ ] Host-to-host certificates pinned where peers call each other
• [ ] Specfiles tested against smallest and largest hosts in the pool
• [ ] Storage and network design reviewed for pledge re-placement scenarios you care about
• [ ] HA expectations documented without assuming discovery equals failover

Next steps

• Architecture — layer diagrams and separated tiers
• Networking & certificates — bridges, TLS, peer trust
• VMs & Electros — targets, VM create flow, AtomOS GUI
• Install & CLI reference — authoritative port list