Multi-tenancy, security, and isolation

Security on AtomOS spans the host OS, AtomOS services, Electros organisation controls, and guest configuration. No single switch delivers “tenant isolation”; you combine network design, permissions, storage boundaries, TLS trust, and operational discipline.

Use atomos-cli on the host for install, certificates, vaults, local GUI users, and health checks. Use Electros for organisation-wide roles and fleet operations. See Install with atomos-cli and VMs & Electros.

Security boundaries (mental model)

flowchart TB
  subgraph org["Organisation plane"]
    EL[Electros users and roles]
  end
  subgraph mgmt["Management plane"]
    HTTPS[HTTPS to AtomOS APIs / GUI]
    SSH[SSH / Cockpit on host OS]
  end
  subgraph host["AtomOS host"]
    CLI[atomos-cli as root]
    SVC[Compute / storage / cluster services]
    KVM[KVM / libvirt guests]
    PIN[Pinned peer certificates]
    HMAC[Cluster HMAC secret]
  end
  EL -->|TLS + fingerprint approval| HTTPS
  HTTPS --> SVC
  CLI --> SVC
  SSH --> host
  SVC --> KVM
  SVC <-->|TLS + pin / HMAC where configured| PIN
  SVC --- HMAC

Boundary	Mechanism	Implemented in product vs your responsibility
Electros ↔ AtomOS target	TLS to AtomOS HTTPS services; operator approves host certificate fingerprint	Implemented (HTTPS default from AtomOS 0.9); you must verify fingerprints
AtomOS host ↔ AtomOS host	TLS for service traffic; certificate pinning via atomos-cli --get-certificate; HMAC cluster auth with shared secret	Building blocks are product-side; you configure trust and secrets consistently. This is not automatically mutual TLS (mTLS)
Tenant ↔ tenant (VMs)	Separate VMs, networks, volumes; Electros permissions	Isolation primitives implemented; policy enforcement is your design
Operator ↔ host OS	Linux accounts, sudo, SSH hardening	Host OS — recommended hardening is your baseline
Guest ↔ guest	Virtual networking and hypervisor isolation	Implemented at KVM layer; misconfiguration (shared bridges, shared secrets) breaks isolation

Management access

Surface	Purpose	Hardening notes
Electros	Fleet UI, targets, scenarios, VM lifecycle	Organisation MFA/policy per your IdP; least-privilege roles
AtomOS GUI (atomosgui, from 0.9)	On-host Electros-like UI for local users	Expose only on trusted networks; see GUI ports in install reference
atomos-cli	Install, vaults, certs, service control	Requires root/sudo; restrict SSH and audit usage
Cockpit (9090)	Generic host OS admin	Complementary; not a substitute for AtomOS API auth
SSH (22)	Break-glass host access	Keys, bastion, allow lists; separate from guest bridge traffic when possible

Root is not RBAC

Electros roles and AtomOS GUI groups do not replace root for atomos-cli --install, certificate generation, or deep service maintenance.

Authentication and RBAC

Electros (organisation)

Electros organisation roles and permissions control who may:

• Register and trust AtomOS targets
• Enable hosts under Active Connections / scenarios
• Create and operate IaaS resources (VMs, networks, volumes) within policy

Authoritative UI documentation: Electros user guide. Registration flow: VMs & Electros.

AtomOS GUI (local host)

Local users are managed on the host:

sudo atomos-cli -mu

Group	Scope
storage	Storage-related operations on this host
compute	Compute-related operations on this host
admin	Compute, storage, and network on this host

Group membership flags: atomos-cli --group-add / --group-del (see Install & CLI reference). Full table: Install — local users.

Implemented vs recommended

Practice	Status
HTTPS for AtomOS services (0.9+)	Implemented — generate certs with atomos-cli --generate-cert
Fingerprint verification for Electros targets	Implemented — atomos-cli --show-fingerprint
Peer certificate pinning	Implemented — atomos-cli --get-certificate HOST SERVICE
Electros organisation RBAC	Implemented in Electros
Local GUI groups (storage, compute, admin)	Implemented on hosts with AtomOS GUI
MFA for Electros	Recommended — configure via your organisation IdP where supported
Centralised SIEM for all AtomOS audit events	Recommended — depends on your logging pipeline
Allow/ban client UID lists	Available via atomos-cli allow/ban list flags — your policy

Tenant isolation

Infrastructure isolation (what AtomOS and KVM provide):

• Separate VM domains, virtual NICs, and volume attachments
• Vault paths under /mnt scoped by storage configuration
• Optional client UID allow/ban lists for API clients

Organisation isolation (what Electros provides):

• Which targets and scenarios a user or team may use
• Separation of admin vs operator vs self-service roles

Recommended (not automatic):

• Management VLAN vs tenant VM networks (Networking, VLANs where used)
• No shared SSH keys across tenants
• Separate backup jobs and restore permissions per tenant class

MSP pattern

Multi-customer MSP deployments typically combine multiple hosts, Electros organisation structure, and network segmentation per customer. Validate on a PoC before production SLAs.

TLS certificates (from AtomOS 0.9)

From AtomOS 0.9, service traffic uses HTTPS. Generate certificates that include every IP and DNS name clients use:

sudo atomos-cli --generate-cert
sudo atomos-cli -ra

Show the fingerprint Electros must match:

sudo atomos-cli --show-fingerprint

Electros trust: compare fingerprint on the host with the trust prompt in Connections → Targets (Electros v3.1.6+ trust-host flow). Details: Networking & certificates.

Peer trust: on each host that must call a peer, run --get-certificate for that peer IP and service role (compute or storage), confirm the fingerprint, and save the pinned certificate when prompted. Repeat for every address peers use.

TLS terminology (use precisely)

Term	Meaning here
TLS transport encryption	HTTPS/TLS protects bytes on the wire to AtomOS services (from 0.9)
Server certificate validation	Client checks the server cert (and optionally verification toggles via --set-cert-verify)
Certificate pinning	Operator stores a specific peer certificate after fingerprint check (--get-certificate)
Client certificate authentication	Client presents a certificate during TLS handshake
Mutual TLS (mTLS)	Both sides present and validate certificates during TLS negotiation
HMAC cluster authentication	Shared ELEMENTO_CLUSTER_SECRET used to sign cluster messages — orthogonal to mTLS
Authorization	Whether the authenticated caller may perform an action (Electros RBAC, GUI groups, allow lists)

mTLS vs pinning

Public AtomOS documentation describes HTTPS, fingerprint approval, certificate pinning, and HMAC cluster secrets. Do not equate pinning or HMAC with mutual TLS unless your deployment explicitly enables and validates client certificates during TLS negotiation.

Item	Implemented	Recommended
Self-signed or CLI-generated host certs	Yes	Document SAN list; renew before expiry
Enterprise PKI integration	Depends on deployment	Use org CA where policy requires
Certificate verification toggle	--set-cert-verify	Leave verification enabled in production

Cluster secrets (ELEMENTO_CLUSTER_SECRET)

Hosts in the same logical cluster use a shared secret for host-to-host HMAC authentication on cluster-related traffic. Treat it as key material, not documentation content.

Topic	Guidance
Purpose	Shared secret so only configured peers authenticate to one another
Configuration	Set consistently on every host that must participate in the same cluster; follow install/runbook for your release (environment or config location on the host—confirm with atomos-cli --help and Elemento support)
Documentation	Never paste live secret values into tickets, wikis, or chat
Rotation	Plan rotation in a maintenance window: update all members, restart affected services, verify peer connectivity—details are deployment-specific; contact support if unsure
Recovery	If secrets diverge, peers fail authentication (symptoms resemble “split” cluster); realign secret or rebuild trust per runbook

Secret leakage

If a cluster secret is exposed, assume cluster authentication is compromised until you rotate and validate all peers.

Host hardening

Control	Implemented in AtomOS	Recommended baseline
FirewallD awareness	atomos-cli --fw-info exposes context	Restrict management SSH; open only required ports
OS patching	Host distro (dnf update, etc.)	Regular kernel and QEMU/libvirt updates
Minimal services	Your install role choice	Disable unused roles and Cockpit exposure if not needed
SELinux	Distro default on AlmaLinux/Rocky	Do not disable without compensating controls

Audit logging

Source	What you get
AtomOS services	Service journals — atomos-cli --journal SERVICE TIME
Electros	Organisation action history per Electros product capabilities
Linux	/var/log/secure, auditd if enabled

Centralised retention, tamper protection, and correlation IDs are recommended for regulated environments—not a single bundled SIEM in AtomOS.

Guest security: Secure Boot, vTPM, confidential VMs

Feature	Notes
Secure Boot for guests	Available when firmware, guest OS, and VM configuration support it—enable where compliance requires
vTPM	Supported when configured for the guest and workload needs attestation/secrets
Intel TDX / confidential computing	Specialized topology and release constraints — see Confidential computing (TDX)

Validate guest firmware settings in a lab before production compliance claims.

Production checklist

Implemented capabilities you should use:

• [ ] HTTPS certs generated and SANs complete (atomos-cli --generate-cert)
• [ ] Electros fingerprint verified for every target
• [ ] Peer certificates exchanged for multi-host clusters
• [ ] Cluster secret aligned on all members (never logged)
• [ ] Electros role matrix documented
• [ ] AtomOS GUI local users only where needed; groups least-privilege

Recommended practices:

• [ ] Management network separation
• [ ] Backup encryption and off-site copies (Backup)
• [ ] Restore drills
• [ ] Incident runbook for cert expiry and secret mismatch
• [ ] Guest patching and hardening standard

Related reading

• Networking & certificates
• Architecture — trust boundaries
• Availability & recovery
• Confidential computing (TDX)