Omni is licensed under the Business Source License and requires a support contract for production use. Contact Sidero sales for a production license.
Prerequisites
You will need:- A Linux host with at least 2 vCPUs and 4 GB RAM
- A domain name or IP address for your Omni instance
- Docker installed on the host
- The following ports open and accessible:
Step 1: Install Docker
Omni and its supporting services run as Docker containers. Follow the official Docker installation guide for your Linux distribution. After installing, add your user to thedocker group so you can run Docker without sudo:
Step 2: Install cfssl
cfssl generates and signs the TLS certificates used by Omni and Dex.
Step 3: Set environment variables
Set variables that define your host’s network addresses and the internal hostnames for Omni and Dex. They are referenced throughout the guide, so set them before proceeding.If your host does not have a public IP (e.g. a local VM), set
HOST_PUBLIC_IP to the IP your local machine uses to reach the host.3.1: Add internal hostnames to /etc/hosts
Omni and Dex use .internal hostnames that are not registered in public DNS. This maps them to localhost so the host can resolve them.
Step 4: Generate TLS certificates
Omni and Dex communicate over TLS. In this step, you create a root CA and use it to sign a certificate covering both service endpoints. The CA certificate is also distributed to client machines in Step 9 so their browsers trust the Omni UI.If you already have a trusted internal CA, use it to sign the certificate in Step 4.3 and skip Steps 4.1 and 4.2.
4.1: Create the root CA
Run this command to generate a self-signed root CA, the trust anchor for all certificates in this setup. It producesca-key.pem (private key), ca.pem (public cert), and ca.csr (signing request).
4.2: Create the signing configuration
Create a signing configuration that tellscfssl how to sign certificates. The web-server profile is used for Omni and Dex. The client profile is used for external etcd authentication.
4.3: Generate the server certificate
Generate a single wildcard certificate covering both the Omni and Dex endpoints. Both IPs are included so TLS connections work regardless of whether clients connect by hostname or IP.server-key.pem (private key), server.pem (public cert), and server-chain.pem (cert bundled with CA). Make them readable by all service users by running:
Step 5: Generate the etcd encryption key
Omni encrypts all data written to etcd at rest using a GPG key. This generates the key and exports it toomni.asc, which Omni reads on startup.
Step 6: Set up an identity provider
Omni requires an OIDC or SAML identity provider for user authentication. This guide uses Dex, configured with a static user. Dex can also act as a proxy to upstream providers such as LDAP, SAML, GitHub, and Okta, see the Dex connector documentation for details. If you already have an existing SAML or OIDC provider and want to connect it directly to Omni, skip this step and see Authentication and Authorization.6.1: Create a password hash for the admin user
You will be prompted to enter a password. This becomes your Omni login password. The hash is stored in the Dex configuration and never transmitted in plain text.6.2: Write the Dex configuration
Create adex.yaml configuration file, which configures Dex to serve OIDC over TLS on port 5556, registers Omni as an OAuth2 client, and creates a single static login user.
6.3: Run Dex
Start Dex as a container, mounting the configuration file and TLS certificates. The:Z flag on volume mounts ensures compatibility with SELinux if it is enabled on your host.
Step 7: Run Omni
In this step you will start the Omni container and connect it to the services you set up in the previous steps: the TLS certificates from Step 4, the encryption key from Step 5, and the identity provider from Step 6.7.1: Get the latest Omni version
Fetch the latest Omni release tag from GitHub and store it inOMNI_VERSION:
7.2: Merge the CA trust bundle
Step 7.5 mounts a certificate at/etc/ssl/certs/ca-certificates.crt so the container trusts the certificate generated in Step 4. This path is also the container’s system trust store, used to verify TLS connections to external hosts such as the Image Factory. Merge your CA into the image’s existing trust bundle so both the internal certificate and the standard public certificate authorities remain trusted:
7.3: Create the SQLite storage directory
Omni uses SQLite alongside etcd for certain internal state. This command creates the directory on the host that will be mounted into the container:7.4: Accept the EULA
Omni requires acceptance of the End User License Agreement (EULA) to start. Acceptance is recorded the first time Omni starts with a name and email address, and starting Omni with a different name or email updates the record.If your organization has a separate agreement with Sidero Labs, that agreement takes precedence and the EULA does not apply. Omni still requires the acceptance values below to start.
--eula-accept-name and --eula-accept-email flags from the EULA_NAME and EULA_EMAIL environment variables. Set them to your own values:
eulaAccept in the Omni configuration reference.
7.5: Start Omni
Choose the etcd mode that matches your setup. Embedded etcd is suitable for a single Omni instance. External etcd is required for high availability or if you need to manage the datastore independently. The commands below use CLI flags to start Omni. If you prefer to use a configuration file instead, see Omni configuration Examples. The OIDC client secret from Step 6.2 is set with theOMNI_AUTH_OIDC_CLIENT_SECRET environment variable.
- Embedded etcd (default)
- External etcd
Omni uses embedded etcd for cluster state. This command creates the directory on the host that will be mounted into the container:With the etcd directory in place, start the Omni container:
Step 8: Verify services are running
Check that both Omni and Dex containers started successfully:Step 9: Access the Omni UI
Omni is running on your host, but your local machine does not yet trust the CA certificate or know how to resolve the internal hostnames. The steps below set that up.9.1: Copy the CA certificate to your local machine
Copyca.pem from the host to your local machine. You will install it as a trusted root in the next step.
- AWS
- GCP
- DigitalOcean / Bare metal / Local VM
Replace
<HOST_PUBLIC_IP> with your instance’s public IP and ~/path/to/your-key.pem with your SSH key path.9.2: Trust the CA certificate
Add the CA to your local machine’s system trust store. This tells your browser and OS to trust TLS certificates signed by this CA, including the Omni and Dex endpoints.- Linux (RHEL)
- Linux (Ubuntu)
- macOS
- Windows
On Red Hat and Fedora based distros you can copy the
ca.pem file into the /etc/pki/ca-trust/source/anchors/ folder and then run the following command to generate the trusted root store:9.3: Add internal hostnames to your local hosts file
Map the Omni and Dex hostnames to your host’s public IP so your local machine can resolve them. Replace<HOST_PUBLIC_IP> with your host’s public IP.
- macOS / Linux
- Windows
9.4: Log into Omni
Openhttps://omni.internal in your browser and sign in with the email from Step 3 and the password from Step 6.1.
Step 10: Connect machines
Machines connect to Omni through the SideroLink API athttps://omni.internal:8090. Because omni.internal is not a public DNS name and its certificate is signed by the CA from Step 4, machines need to resolve the hostname and trust the CA. Each requirement is met by the following:
- Name resolution: A DNS record for
omni.internalon the machines’ network, or aStaticHostConfigdocument.StaticHostConfigrequires Talos Linux 1.12 or later. - CA trust: A
TrustedRootsConfigdocument with the CA certificate.
-
On your local machine, open the Omni Home page and click Download Machine Join Config. The browser saves the join configuration to your downloads folder as
machine-config.yaml, or with a number added to the name if a file with that name already exists. -
On your local machine, set the public IP of the Omni host. Replace
<HOST_PUBLIC_IP>with the public IP: -
In the same terminal, append the
StaticHostConfigandTrustedRootsConfigdocuments tomachine-config.yaml, with theca.pemfile you copied in Step 9.1. Run the command from the folder that contains both files, and replacemachine-config.yamlwith the name of the downloaded file if it differs: -
Provide the combined file to each machine at first boot. The method depends on the platform:
- Cloud platforms, such as AWS, GCP, Azure, and DigitalOcean: Paste the file into the user data of the instance.
- Proxmox: Provide the file through the NoCloud datasource.
- Bare metal: Serve the file over HTTP and add the
talos.configkernel argument with its URL to the default kernel arguments, for example through a PXE boot or an Image Factory schematic.