Install AtomOS
Install atomos-cli, then deploy compute, storage, full, or AtomOS GUI roles on a supported Linux host. On an installed build, atomos-cli --help is authoritative if a flag differs from this guide.
Example walkthrough: asciinema recording.
For a condensed first-deployment path, see Quick start.
Prerequisites
- Root privileges (
sudo) for install and most management commands. - x86_64 only.
- Supported distributions: Hardware & platforms. Prefer AlmaLinux 9 for compute and full nodes.
- Installer minimum checks: 2 CPU cores, 2 GB RAM. Use the hardware sizing table for real workloads.
- Outbound access to your distro package repositories and Elemento endpoints (
idp,repo,portal). - Console or BMC (IPMI/iDRAC/iLO) access before changing network bridges.
Remote install risk
Bridging the active management NIC can interrupt SSH. Do not run bridge setup on a production host without out-of-band console access and a tested recovery plan. See Networking.
1. Install atomos-cli
Prefer download, review, then execute:
curl -fsSL https://repo.elemento.cloud/get-atomos.sh -o /tmp/get-atomos.sh
# Review /tmp/get-atomos.sh, then:
sudo bash /tmp/get-atomos.shTrust boundary
curl | bash is convenient but skips review. The download-then-execute form above is preferred for production hosts.
The script installs atomos-cli (typically to /usr/bin/atomos-cli) and may enable a periodic update check. From AtomOS 0.9, the CLI is named atomos-cli (previously nucleus).
2. Choose a role and install
Use on-prem or cloud according to where the machine lives. Follow interactive prompts after each command.
AlmaLinux / Rocky (RHEL family)
| Role | On-prem example | Cloud example |
|---|---|---|
| Compute | sudo atomos-cli --install compute on-prem | sudo atomos-cli --install compute cloud |
| Storage | sudo atomos-cli --install storage on-prem | sudo atomos-cli --install storage cloud |
| Full (compute + storage) | sudo atomos-cli --install full on-prem | sudo atomos-cli --install full cloud |
| AtomOS GUI | sudo atomos-cli --install atomosgui on-prem | sudo atomos-cli --install atomosgui cloud |
Ubuntu / Debian
| Role | On-prem example | Cloud example |
|---|---|---|
| Storage | sudo atomos-cli --install storage on-prem | sudo atomos-cli --install storage cloud |
| AtomOS GUI | sudo atomos-cli --install atomosgui on-prem | sudo atomos-cli --install atomosgui cloud |
Compute and full packages are not available on Ubuntu/Debian.
Cloud networking
Some CSPs inject an IPv6 default route that breaks package installs. Run sudo atomos-cli --verify-network and confirm the install interface has working internet before continuing.
3. Network bridge
During install, atomos-cli may prompt for a NIC and create a bridge (default br0) with NetworkManager (nmcli). To run the bridge wizard later:
sudo atomos-cli --bridge-setupPrefer a NIC dedicated to guest traffic when possible. Keep SSH/Electros management on a separate interface when you can. Details: Networking & certificates and VLANs.
4. Modules
After install, fetch optional modules from the Elemento repository:
sudo atomos-cli --modules
sudo atomos-cli --remove-modulesFlag name
The remove flag is --remove-modules (plural).
5. Vaults (storage or full)
Storage and full installs create the default Elemento vault and can create additional vaults:
sudo atomos-cli --vault-creator
sudo atomos-cli --vault-editor
sudo atomos-cli --restart storageRestart storage only after vault setting changes and in an approved window. Details: Storage.
6. HTTPS certificates
From AtomOS 0.9, services speak HTTPS. New installs prompt for certificate creation. To generate or renew later:
sudo atomos-cli --generate-cert
sudo atomos-cli -raInclude every IP and DNS name used to reach the host as SANs. Trust the fingerprint from Electros and from peer hosts — see Networking & certificates.
7. Local users (AtomOS GUI)
When AtomOS GUI is installed, create local users and assign groups:
sudo atomos-cli -mu| Group | Permissions |
|---|---|
storage | Manage storage resources |
compute | Manage compute resources |
admin | Manage compute, storage, and network |
8. Cluster authentication (multi-host)
Cooperating nodes authenticate cluster messages using a shared secret derived from ELEMENTO_CLUSTER_SECRET (when configured). All peers that must trust each other need a consistent secret.
Secrets handling
Do not put cluster secrets in shell history, process arguments visible to other users, chat logs, or committed files. Provision via a controlled configuration channel, restrict file permissions, and document rotation. See Security.
Exact interactive prompts vary by installer build — confirm with your release notes and atomos-cli --help.
9. Verify and reboot
sudo atomos-cli --verify-install
sudo atomos-cli --infoReboot once so services and kernel modules settle, then register the host in Electros (VMs & Electros) or use AtomOS GUI.
10. First virtual machine
Create the first VM through Electros (documented VM flow) or AtomOS GUI when available. Prefer the Electros UI path when that is your operational standard.
Validate: power state, console, network, and attached volumes.
Troubleshooting installation
sudo atomos-cli --logs
sudo atomos-cli --status
sudo atomos-cli --helpPorts, endpoints, and the curated command map: CLI & ports reference. Runbooks: Troubleshooting. Support: support@elemento.cloud.