Install and CLI reference
Authoritative ports, endpoints, and a curated atomos-cli flag reference for operators and automation authors. Flag names and subcommands can change between builds — on every host, atomos-cli --help and atomos-cli --version override this page.
When docs and CLI disagree
Treat the installed CLI as source of truth. Use this reference for planning (firewall, Electros targets, peer trust) and as a stable link target from other guides.
Application ports
AtomOS services listen on the host for inter-service traffic, Electros/API clients, and cluster coordination. Not every port below must be reachable from untrusted networks. Restrict exposure to management subnets, Electros egress paths, and peer hosts that participate in cluster or storage operations.
| Service | TCP | UDP |
|---|---|---|
| GUI | 7780, 7781 | — |
| Client | 7701, 7771, 17777 | 7771, 7775 |
| Cluster | 4244–4247 | 4243 |
| Compute | 3289, 4242, 7704, 7774, 7776, 7777, 50152 | 7704, 7774, 7778 |
| Storage | 3260, 7772, 7773, 7775, 27777 | 7772, 7773 |
Notes:
- TCP ports carry request/response APIs, exports, and control channels unless your release documentation states otherwise.
- UDP ports support discovery, heartbeat, or datagram-side cluster/compute paths on the paths you enable — confirm listeners with
ss -tulpnon the host (Diagnostic commands). - 3260 is commonly associated with iSCSI-style targets when that path is in use on the host.
- 27777 is the storage client REST endpoint (often probed on loopback during troubleshooting).
Define firewall direction, sources, and destinations per role (compute, storage, full) and per integration (Electros, peer hosts, backup tools).
Access services
Optional or environmental services on the host OS — not AtomOS product ports, but frequently relevant in runbooks:
| Service | Ports | Typical use |
|---|---|---|
| SSH | TCP 22 | Host administration |
| VNC | TCP 5900–5999 | Guest console when enabled |
| Cockpit | TCP 9090 | Web-based host UI when installed |
Required endpoints (outbound)
Hosts need outbound HTTPS (and distro package mirrors) for install and updates:
- Your Linux distribution package repositories
idp.elemento.cloudrepo.elemento.cloudportal.elemento.cloud
Bootstrap (atomos-cli installer)
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.shThe script installs atomos-cli (typically /usr/bin/atomos-cli) and may configure periodic update checks. From the published AtomOS 0.9 milestone onward, the CLI is named atomos-cli (formerly nucleus).
Full install walkthrough: Install AtomOS.
Role installs
Syntax:
sudo atomos-cli --install SERVICE TYPESERVICE | Purpose |
|---|---|
compute | Hypervisor and compute stack |
storage | Storage services and vault management |
full | Compute and storage on one host |
atomosgui | On-host management UI (from 0.9 milestone) |
TYPE | When to use |
|---|---|
on-prem | Physical servers or self-managed VMs in your datacenter |
cloud | CSP bare-metal or nested-virt instances with provider networking quirks |
On-prem examples (AlmaLinux / Rocky — adjust for your matrix):
sudo atomos-cli --install compute on-prem
sudo atomos-cli --install storage on-prem
sudo atomos-cli --install full on-prem
sudo atomos-cli --install atomosgui on-premUse cloud instead of on-prem when the machine is a cloud instance. Compute and full roles are not available on all distributions — see Install AtomOS.
Interactive prompts (bridge, vault, certificates) follow the command; complete them before relying on Electros registration.
Flag groups
Columns: Root? — requires sudo for typical production hosts. Disruptive? — may interrupt VMs, storage I/O, or network sessions.
Install and packages
| Syntax | Purpose | Root? | Disruptive? | Example |
|---|---|---|---|---|
-i, --install SERVICE TYPE | Install a role | Yes | Yes (packages, services) | sudo atomos-cli --install full on-prem |
-vs, --verify-install | Post-install verification | Yes | No | sudo atomos-cli --verify-install |
-m, --modules | Install optional modules | Yes | Yes | sudo atomos-cli --modules |
--remove-modules | Remove optional modules | Yes | Yes | sudo atomos-cli --remove-modules |
-u, --update | Update AtomOS packages | Yes | Yes (service restarts) | sudo atomos-cli --update |
-c, --check | Check whether AtomOS is installed | No* | No | atomos-cli --check |
-v, --version | Show package versions | No* | No | atomos-cli --version |
-U, --uninstall | Uninstall AtomOS | Yes | Yes (data risk) | sudo atomos-cli --uninstall |
-rl, --logs | Installation / service logs | Yes | No | sudo atomos-cli --logs |
-l, --license | Check license file | Yes | No | sudo atomos-cli --license |
--checkupdate | Check for CLI updates | No* | No | atomos-cli --checkupdate |
-dr, --dry-run | Dry-run supported operations | Varies | No | sudo atomos-cli --dry-run … |
*Some environments still require root to read package state; if permission denied, retry with sudo.
Services
| Syntax | Purpose | Root? | Disruptive? | Example |
|---|---|---|---|---|
-s, --status | Service status summary | Yes | No | sudo atomos-cli --status |
-j, --journal SERVICE TIME | Journal slice for a service | Yes | No | sudo atomos-cli --journal storage 1h |
--start SERVICE | Start one service | Yes | Can affect workloads | sudo atomos-cli --start compute |
--stop SERVICE | Stop one service | Yes | Yes | sudo atomos-cli --stop compute |
--restart SERVICE | Restart one service | Yes | Yes | sudo atomos-cli --restart storage |
-sa, --start-all | Start all AtomOS services | Yes | Can affect workloads | sudo atomos-cli --start-all |
-ta, --stop-all | Stop all AtomOS services | Yes | Yes | sudo atomos-cli --stop-all |
-ra, --restart-all | Restart all services | Yes | Yes | sudo atomos-cli -ra |
-hr, --hard-restart | Hard restart all | Yes | Yes | sudo atomos-cli --hard-restart |
-r, --reset | Reset storage service | Yes | Yes (storage path) | sudo atomos-cli --reset |
Common service names in runbooks: compute, storage, and cluster-related units — confirm exact names with --status on your build.
Storage
| Syntax | Purpose | Root? | Disruptive? | Example |
|---|---|---|---|---|
--vault-creator | Interactive vault creation | Yes | Yes (mount layout) | sudo atomos-cli --vault-creator |
--vault-editor | Edit vault parameters | Yes | Yes (placement rules) | sudo atomos-cli --vault-editor |
--volume-info | Volume and vault information | Yes | No | sudo atomos-cli --volume-info |
Manage vault settings.json through these wizards — do not hand-edit unless Elemento support instructs break-glass edits. See Storage & vaults.
Network and TLS
| Syntax | Purpose | Root? | Disruptive? | Example |
|---|---|---|---|---|
--bridge-setup | Create or adjust Linux bridge (e.g. br0) | Yes | Yes (can drop SSH) | sudo atomos-cli --bridge-setup |
--delete-bridge | Remove bridge configuration | Yes | Yes | sudo atomos-cli --delete-bridge |
-vn, --verify-network | Default route / connectivity checks | Yes | No | sudo atomos-cli --verify-network |
-crt, --generate-cert | Generate TLS certificate for host APIs | Yes | Yes (requires service restart) | sudo atomos-cli --generate-cert |
--show-fingerprint | Show local certificate fingerprint | Yes | No | sudo atomos-cli --show-fingerprint |
--get-certificate HOST SERVICE | Fetch and pin peer certificate | Yes | No | sudo atomos-cli --get-certificate 10.0.0.11 compute |
--set-cert-verify | Enable or disable certificate verification | Yes | Yes (security impact) | sudo atomos-cli --set-cert-verify |
--fw-info | FirewallD configuration summary | Yes | No | sudo atomos-cli --fw-info |
From AtomOS 0.9, host APIs default to HTTPS. After --generate-cert, restart services (-ra) and re-trust fingerprints in Electros and on peers — Networking & certificates.
Users, health, and allow lists
| Syntax | Purpose | Root? | Disruptive? | Example |
|---|---|---|---|---|
-mu | Manage local AtomOS GUI users | Yes | Yes (access) | sudo atomos-cli -mu |
-ga, --group-add | Add GUI group membership | Yes | Yes | sudo atomos-cli --group-add |
-gd, --group-del | Remove GUI group membership | Yes | Yes | sudo atomos-cli --group-del |
-I, --info | Host and AtomOS information | Yes | No | sudo atomos-cli --info |
--healthcheck | Resource health check | Yes | No | sudo atomos-cli --healthcheck |
--pci-list | PCI devices and drivers | Yes | No | sudo atomos-cli --pci-list |
--create-allow-list / --create-ban-list | Create UID lists | Yes | Yes | sudo atomos-cli --create-allow-list |
--add-allow-list / --add-ban-list | Add client UIDs | Yes | Yes | sudo atomos-cli --add-allow-list |
--remove-allow-list / --remove-ban-list | Remove UIDs | Yes | Yes | sudo atomos-cli --remove-allow-list |
--disable-allow-list / --resume-allow-list | Pause or enforce allow list | Yes | Yes | sudo atomos-cli --resume-allow-list |
--disable-ban-list / --resume-ban-list | Pause or enforce ban list | Yes | Yes | sudo atomos-cli --resume-ban-list |
GUI groups (storage, compute, admin) are documented in Install AtomOS.
Cluster authentication (ELEMENTO_CLUSTER_SECRET)
Multi-host deployments authenticate cluster-related traffic using a shared secret derived from ELEMENTO_CLUSTER_SECRET when that variable is configured on the host. All peers in the same logical cluster must use a consistent value.
Configuration channel
This reference does not document a CLI flag to unset or rotate the secret. Provision and rotate via the install/runbook channel Elemento provides for your release (environment file, configuration directory, or installer prompt). Confirm locations with atomos-cli --help, Security architecture, and support — never paste live secrets into tickets or wikis.
Symptoms of mismatched secrets resemble partial cluster visibility or failed peer authentication; align secrets in a maintenance window and validate with --status and Electros target health.
Common sequences
Fresh storage node:
sudo atomos-cli --install storage on-prem
sudo atomos-cli --modules
sudo atomos-cli --vault-creator
sudo atomos-cli --generate-cert
sudo atomos-cli -ra
sudo atomos-cli --show-fingerprintCompute node joining existing fleet:
sudo atomos-cli --install compute on-prem
sudo atomos-cli --bridge-setup
sudo atomos-cli --verify-network
sudo atomos-cli --generate-cert
sudo atomos-cli --get-certificate 10.0.0.20 storage
sudo atomos-cli -raPost-change validation:
sudo atomos-cli --verify-install
sudo atomos-cli --status
sudo atomos-cli --healthcheck
sudo atomos-cli --volume-infoRelated: Diagnostic commands, Troubleshooting, Upgrades.