Getting Started with Omni

This guide walks you through creating a high-availability Kubernetes cluster managed by Omni using Talos Linux. While the example uses UTM/QEMU for local virtualization, the same process applies to bare metal machines, cloud instances, or edge devices. If you just want to evaluate Omni quickly, you can register a few disposable local machines with Omni in minutes, then build a cluster from them, before working through the full guide.

Try Omni out in ~5 minutes locally

Want to evaluate Omni without provisioning real machines? On macOS or Linux you can boot throwaway VMs locally with QEMU and register them with your Omni instance.

This is a local trial path for evaluation only. For bare metal, cloud, or edge deployments, see the rest of this guide.

You’ll need talosctl 1.12+ and omnictl installed:

  brew install siderolabs/tap/sidero-tools

Boot temporary VMs that auto-register with Omni as available machines:

  sudo -E talosctl cluster create qemu \
    --name talos-omni-cluster-default  \
    --omni-api-endpoint $(omnictl jointoken omni-endpoint) \
    --workers 0 --controlplanes 3

After a minute or two, the VMs appear under Machines in your Omni dashboard as available machines, they aren’t a cluster yet. Continue to Step 3: Create cluster to build a cluster from them.Tear down when you’re done:

  sudo -E talosctl cluster destroy --name talos-omni-cluster-default

For a visual walkthrough of the full setup covered in this guide, see the video below:

Prerequisites

You must have the following to create a cluster with Omni:

Network access: Your machines must have outbound internet access and be able to reach the WireGuard endpoint shown on your Omni Home panel. This endpoint lists an IP address and port (e.g., 199.99.99.100:10001) that nodes connect to. Machines need to reach that address over:
- UDP on the specified port (for WireGuard)
- TCP on port 443 (for Omni communication)
Virtual or physical machines: You can use any virtualization platform that supports booting from an ISO image, for example, UTM, Proxmox, or VMware Fusion. Alternatively, you can deploy on cloud platforms or physical hardware. Bare metal systems can boot using a CD, USB drive, virtual media, or PXE.
CLI tools: To work effectively with Omni, you’ll need the CLI tools omnictl, talosctl, and kubelogin. Download talosctl, kubectl, kubectl-oidc-login, and omnictl for macOS and Linux systems by running this command:
brew install siderolabs/tap/sidero-tools
For manual and Windows installation, refer to the alternate installation methods in the Talos documentation.
talosconfig and omniconfig files: Download the talosconfig and omniconfig configuration files from your Omni dashboard. These files let you manage your Talos nodes and connect to Omni from your local environment. Alternatively, you can download the talosconfig file from the CLI by running the following command. Replace the <cluster-name> placeholder with your cluster’s name:
omnictl talosconfig --cluster <cluster-name>
Once you’ve set up these prerequisites, you can move on to creating your cluster with Omni.

Step 1: Download installation media

Omni is a Bring Your Own Machine platform. You only need to boot a machine from a Talos Omni image configured to connect to your Omni instance. You can download the Talos Omni image using either the CLI or the Omni UI:

CLI
Omni UI

Run the following command to download a Talos Omni ISO image:

omnictl download iso

To see additional options such as targeting different machines or adding extensions and customizations, run:

omnictl download iso --help

Step 2: Boot your machines

Boot each machine you want to add to the cluster using the Omni image you downloaded in Step 1. After the machines have booted, they’ll appear in the Machines section. Depending on your environment, you can use the following methods:

If your environment is not listed here, see the Register machines with Omni documentation for more details

Local (QEMU / UTM)
AWS EC2
PXE Boot

To create temporary VMs on your local system (requires Talosctl v1.12+):

talosctl cluster create qemu --omni-api-endpoint $(omnictl jointoken omni-endpoint) --workers 0 --controlplanes 3

This command boots virtual machines locally and connects them to your Omni instance.

If you have omnictl configured, you can create EC2 instances directly:

aws ec2 run-instances \
    --image-id $(aws ec2 describe-images --owners 540036508848     --filters "Name=architecture,Values=x86_64"     --query 'Images | sort_by(@, &CreationDate) | reverse(@) | [?!contains(Name, `beta`) && !contains(Name, `alpha`) && !contains(Name, `Beta`) && !contains(Name, `Alpha`)] | [0].[ImageId]'     --output text) \
    --count 3 \
    --instance-type t3.small   \
    --associate-public-ip-address \
    --user-data "$(omnictl jointoken machine-config)"

This launches three EC2 instances that automatically join your Omni cluster.

To PXE boot physical machines:

docker run --rm --network host \
  ghcr.io/siderolabs/booter:v0.3.0 \
  --extra-kernel-args "$(omnictl jointoken kernel-args)"

This runs the SideroLabs Booter utility, which provisions PXE-booted machines using your Omni join token.

Machine not appearing? Verify that the machine has outbound access to UDP (the WireGuard port shown on your Omni Home panel) and TCP 443. If a firewall or NAT rule blocks either port, the machine will not be able to register. For more information, see the Prerequisites section and the Omni Firewall and Egress Requirements documentation.

Step 3: Create cluster

Now that your machines are visible in Omni, you can create your cluster either via the UI or cluster templates. Refer to the create a cluster documentation for information on how to create a cluster template. To create a cluster via the Omni UI by following these steps:

In the Omni sidebar, go to Clusters → Create Cluster.
Enter a cluster name and select the Talos Linux and Kubernetes versions.
(Optional) Add configuration patches. See Create a Patch for Cluster Machines to learn how to create and apply patches.
Under the Available Machines section, select at least one machine as a control plane by clicking CP.

For high availability, use an odd number of control plane nodes. We suggest using 3 nodes.

Select one or more worker machines by clicking W0, W1, etc.
Click Create Cluster.

You’ll be redirected to the Cluster Overview page, where you can monitor the cluster’s creation progress.

If the cluster remains in a pending or provisioning state after you click Create Cluster, check the following:

Machine connectivity: Verify that all selected machines are still connected in the Machines list.
etcd quorum: For a 3-node control plane, all three nodes must be healthy before etcd can establish quorum. If one or more nodes are unavailable, cluster creation will stall.
Node startup: Newly provisioned nodes may take a minute or two to finish booting and become ready to join the cluster.

If the issue persists, see the cluster troubleshooting documentation.

Step 4: Download the `kubeconfig` file

To make omnictl, talosctl, and kubectl automatically detect your cluster configuration:

Export your cluster name in a variable, replacing the <cluster-name> variable with your name of the cluster:

export CLUSTER_NAME=<cluster-name>

Merge each configuration file into its default location:

# Merge Omni configuration
omnictl config merge $HOME/Downloads/omniconfig.yaml

# Merge Talos configuration
talosctl config merge $HOME/Downloads/talosconfig.yaml

# Merge kubeconfig
omnictl kubeconfig --cluster $CLUSTER_NAME

Step 5: Access your Kubernetes cluster

Once your cluster is created, you can confirm that your nodes are registered in Kubernetes by running:

kubectl get nodes

The first time you run kubectl, a browser window will open prompting you to sign in with your identity provider (Google or GitHub).If you see the error error: unknown command "oidc-login", ensure you’ve installed the kubectl-oidc-login plugin as described in the prerequisites section.

Step 6: Deploy your first workload

To run your first application on the cluster:

Deploy a sample application:

 kubectl apply -f \
    https://raw.githubusercontent.com/siderolabs/example-workload/refs/heads/main/deploy/example-svc-nodeport.yaml

Verify that the pods and services are running:

kubectl get pods,services

Forward the service port to your local machine:

kubectl port-forward svc/example-workload 8080:8080

To view the application, open http://localhost:8080 in your browser or run:

curl http://localhost:8080

For a more complete example of a production-style cluster, including a monitoring stack, GitOps-based application management, and supporting infrastructure, see the examples in our community contrib repo.

Explore Omni

Congratulations, you have successfully created a Talos Linux cluster with Omni! From here, you can explore what else Omni can do, such as:

Overview

Getting Started

Self Hosted

Infrastructure and Extensions

Omni Cluster Setup

Cluster Management

Security and Authentication

Reference

Troubleshooting and Support

Prerequisites

Step 1: Download installation media

Step 2: Boot your machines

Step 3: Create cluster

Step 4: Download the `kubeconfig` file

Step 5: Access your Kubernetes cluster

Step 6: Deploy your first workload

Explore Omni

​Prerequisites

​Step 1: Download installation media

​Step 2: Boot your machines

​Step 3: Create cluster

​Step 4: Download the kubeconfig file

​Step 5: Access your Kubernetes cluster

​Step 6: Deploy your first workload

​Explore Omni

Prerequisites

Step 1: Download installation media

Step 2: Boot your machines

Step 3: Create cluster

Step 4: Download the `kubeconfig` file

Step 5: Access your Kubernetes cluster

Step 6: Deploy your first workload

Explore Omni