Skip to main content

Omnictl

@dataverket/omnictlv2026.10.27.1· AGPL-3.0-only(was none)· 9d agoBEHAVIORS
01README

Sidero Omni for swamp, through omnictl. Two model types, two roles. @dataverket/omnictl/inventory reads: discover writes one node per managed machine (hardware, network, Talos version, cluster role, connection and readiness), one cluster per cluster and a summary; talosconfig mints one cluster's admin talosconfig for the service account and stores it with the cluster's node IPs, which is everything @dataverket/talosctl/node needs to reach the machines through Omni's proxy; joinTokens lists the join tokens by fingerprint, state and use. A Reader service account. @dataverket/omnictl/cluster writes: applyPatch creates or updates a ConfigPatch, from text or a file in the repository, scoped to a machine, a machine set or a cluster; addMachine puts a machine into a machine set by its MachineSetNode, with the set's role label, without which Omni never allocates it; removeMachine is omnictl cluster machine delete, which drains, wipes and waits; deleteMachine is the dashboard's Delete Machine: the machine's own config patches and its Link, after which Omni tears down the Machine, also when a removal hangs because the server is gone; setExtensions sets the system extensions for a machine, a machine set or a cluster. Every apply takes dryRun. An Operator service account, on its own model instance with its own vault key. Forked from @mccormick/omni (MIT) as @dataverket/omni; renamed after the CLI it wraps. The key is named as a file read at call time (serviceAccountKeyFile) or given as a value from a vault (serviceAccountKey), never both; either way it is marked sensitive and redacted from logs and errors. Both models check before every method that the key resolves and that Omni accepts it, so an expired key stops a run with a message that says so.

02Behaviors2
@dataverket/omnictl/inventoryv2026.10.01.1inventory.ts
fn joinTokens()
List Omni's join tokens as joinToken resources: which is default, which are revoked or expired, and how many machines each has joined. The token itself is never stored, only a SHA-256 fingerprint. Read-only against Omni.
fn discover()
Query Omni for every managed Talos machine and cluster and write
fn talosconfig(cluster: string)
Mint one cluster's admin talosconfig for the service account and store it with the cluster's node IPs as a talosconfig resource. The config names an identity and Omni's proxy, no key; nothing is written to ~/.talos/config. Read-only against Omni.
ArgumentTypeDescription
clusterstringOmni cluster name

Resources

node(30d)— An Omni-managed Talos machine
cluster(30d)— A Talos cluster managed by Omni
summary(30d)— Roll-up of one Omni inventory run
talosconfig(30d)— How to reach one cluster: its admin talosconfig for the service account and its machines' node IPs; a talosctl model takes both by CEL. The config carries an identity, not a key
joinToken(30d)— One Omni join token: name, state, default flag, how many machines joined with it, expiry. A fingerprint stands in for the token
@dataverket/omnictl/clusterv2026.10.01.3cluster.ts
fn applyPatch(data?: string, dataFile?: string, machineSet?: string, cluster?: string, dryRun?: boolean)
Create or update a ConfigPatch scoped to one machine (before or after it joins), a machine set, or a cluster; read it back and store it. dryRun validates only.
ArgumentTypeDescription
data?stringTalos machine config patch, YAML text; or name it with dataFile
dataFile?stringPath of a YAML file holding the patch, read at call time; relative to the repository
machineSet?stringScope the patch to a machine set; needs cluster
cluster?stringScope the patch to a cluster, or name the machine set's cluster
dryRun?booleanValidate with omnictl and change nothing
fn addMachine(cluster: string, machineSet: string, dryRun?: boolean)
Add a machine to a machine set by creating its MachineSetNode, which is what the Omni UI does, with the set's role label copied onto it; Omni then installs Talos with every patch in scope. Refuses a machine set that is missing, of another cluster, or without one role. An existing node is updated. dryRun validates only.
ArgumentTypeDescription
clusterstringCluster name
machineSetstringMachine set id, e.g. <cluster>-workers
dryRun?booleanValidate with omnictl and change nothing
fn removeMachine(timeout?: string)
Remove a machine from its cluster with omnictl cluster machine delete: Omni drains it, wipes it and returns it to the pool; waits up to timeout. Refuses a machine that is in no machine set. Never forces.
ArgumentTypeDescription
timeout?stringHow long omnictl waits for the drain and wipe
fn deleteMachine()
What Omni's dashboard does with Delete Machine: delete the machine's own config patches and its SideroLink Link; Omni then tears down the Machine and its labels (Machines themselves are read-only to every role). Refuses while the machine is in a machine set (removeMachine first), and is a no-op when Omni has no such machine. Delete the server first, or a running machine re-registers. Works whether or not removeMachine's wipe finished, so it also clears a machine whose server is gone and whose re
fn setExtensions(cluster: string, machineSet?: string, extensions: array, dryRun?: boolean)
Create or replace the ExtensionsConfiguration for a machine, a machine set or a cluster, as Omni's UI does; Omni installs the most specific one a machine has, which reboots it into a new schematic. dryRun validates only.
ArgumentTypeDescription
clusterstringCluster name
machineSet?stringScope to a machine set: every machine in it without a configuration of its own
extensionsarrayThe complete list for the scope; it replaces what was there, and [] removes them all
dryRun?booleanValidate with omnictl and change nothing

Resources

configPatch(infinite)— A Talos config patch in Omni, scoped to a machine, a machine set or a cluster
machineSetNode(infinite)— A machine's membership of an Omni machine set
extensionsConfiguration(infinite)— The system extensions Omni installs on a machine, a machine set's machines or a cluster's
03Previous Versions5
2026.10.01.3
2026.10.01.2

Modified 1 behaviors

2026.10.01.1
2026.09.29.1
2026.09.20.1
04Stats
A
100 / 100
Downloads
31
Archive size
49.5 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
05Platforms
06Labels