Configure Omega

Omega is driven entirely by a single profile file (a YAML document). The profile is the source of truth for a device’s identity, how it reaches the platform, which capabilities it runs, and the security policy that governs it. This page is the complete reference: the mental model, every field, how the profile is validated, and a worked walkthrough for writing one.

The mental model: build vs. profile

Two independent things decide what a device can do. Confusing them is the most common source of “why isn’t my module running” questions.

The build decides what is POSSIBLE

Omega is compiled with a set of Cargo features (a “SKU”). A feature that is not compiled in simply does not exist in that binary. See Build Omega.

The profile decides what RUNS

The profile’s modules.required list names the modules to start, and security.capabilities grants the control-plane permissions. Nothing runs unless it is listed.

The two are checked against each other at load time. If the profile names a module or capability that is not compiled into the binary, Omega refuses to start with an exact error — it never runs half-configured. This guarantees that a device which is online is a device whose profile the binary can actually honor.

Where the profile lives and how it loads

Omega loads its profile from a file path passed on the command line:

omega-agent --client /path/to/config.yaml

On an installed device the installer generates this file (commonly config.yaml in the config directory) with the device’s identity and certificate paths filled in, and registers the service to run omega-agent --client <that path>. To regenerate it, delete the file and re-run the installer. There is no hidden fallback: the file named on the command line is the only profile Omega reads. A malformed or invalid profile is fatal (see Validation).

Top-level structure

name: <device-name>          # required
description: <text>          # optional
platform: <os>              # optional (linux | darwin | windows)

connection:                  # how the device reaches the platform
  ...

modules:                     # what runs
  required: [ ... ]

security:                    # capability grants, signing, quotas
  ...

# Optional module-specific sections (only if that module is enabled):
# sqlite-replication: { ... }
# ztna: { ... }
# service-runtime: { ... }
# inventory: { ... }

Field	Required	Description
`name`	Yes	Device / deployment identifier. The only field with no default.
`description`	No	Human-readable label.
`platform`	No	`linux`, `darwin`, or `windows`. If set, a mismatch with the host is warned.
`connection`	Yes	Transport, broker, identity, TLS, enrollment, renewal.
`modules`	Yes	The list of modules to run.
`security`	Recommended	Capability grants, control-message signing, storage/payload quotas.

Anything else at the top level is treated as a module section (e.g. sqlite-replication:) and is decoded by the module that owns it. Unknown sections are warned about (likely a typo or a section for a module you did not enable) but are not fatal.

`connection`

Everything Omega needs to establish an authenticated session with the platform.

connection:
  transport: mqtt                 # mqtt | mqtts | quic | http (dev)
  server_url: mqtts://broker.example.golain.io:8883
  device_id: my-device
  root_topic: /<slug>/my-device   # every topic the device uses hangs off this
  cert_dir: /var/lib/omega/certs  # where enrollment/renewal write the device cert+key
  mqtt:
    keep_alive: 30s
    clean_session: true
    tls:
      ca_cert_path: /var/lib/omega/certs/ca.pem
      client_cert_path: /var/lib/omega/certs/device.crt
      client_key_path: /var/lib/omega/certs/device.key

Field	Description
`transport`	Wire transport. `mqtts` (TLS) is the norm for production; `quic` uses MQTT-over-QUIC; `http` is a development transport.
`server_url`	Broker URL including scheme and port (e.g. `mqtts://host:8883`).
`device_id`	The device’s identity. Must match the certificate CN and the MQTT `client_id` the broker expects.
`root_topic`	The topic prefix every module publishes/subscribes under. All topic names in these docs are relative to it.
`cert_dir`	Directory holding the device certificate and key. Certificate renewal writes here, so it lives at the connection level (it outlives the one-time enrollment block).

`connection.mqtt`

Field	Default	Description
`keep_alive`	`30s`	MQTT keepalive. The broker tears the session down at ~1.5× this with no traffic, so this is the knob for how fast a dark device (power loss, black-holed network) is detected as offline (~45s at the default). Lower = faster detection, more keepalive traffic.
`clean_session`	broker default	MQTT clean-session flag.
`username`, `username_env`, `password_env`	—	Optional broker credentials (prefer the `_env` forms; see Environment overrides).
`tls`	—	TLS material (below).

`connection.mqtt.tls`

Field	Description
`ca_cert_path`	Broker CA bundle. Verifies the broker’s certificate.
`client_cert_path`	The device certificate presented for mutual-TLS.
`client_key_path`	The private key for the client certificate. On a hardware-backed device (TPM / Secure Enclave) there is no key file — the key never leaves the hardware — and this may be blank.

Each path field has a <field>_env twin (ca_cert_path_env, client_cert_path_env, client_key_path_env) that reads the path from an environment variable instead. See Environment overrides.

`connection.jitr` — enrollment

Present only on a device that has not yet enrolled. Just-in-time registration (JITR) exchanges a factory-provisioned bootstrap key/cert for the device’s own certificate, then this block is removed. Full walkthrough: Enrollment (JITR).

Field	Description
`api_base_url`	JITR enrollment endpoint.
`bootstrap_cert_path`	Factory-provisioned bootstrap certificate (public material).
`bootstrap_key_path`	Private key matching the bootstrap cert. Required — enrollment signs a proof-of-possession with it (the bootstrap cert alone is public, so possession of the key is what proves the device belongs to the fleet). PKCS#8/PKCS#1/SEC1 PEM, RSA-2048 or P-256.
`cert_dir`	Where the issued certificate and key are written.
`org_id`, `project_id`, `fleet_id`, `device_name`	Identity the device enrolls under.

The enrollment proof carries a timestamp the platform accepts within a 5-minute window. A factory line with no NTP and a drifted real-time clock fails enrollment — and it fails looking exactly like a bad key. Set the device clock before flashing.

`connection.cert_renewal`

Controls automatic certificate renewal (a background thread; see How renewal works).

Field	Default	Description
`enabled`	`false`	Turn renewal on.
`renew_window_days`	— (min 1)	Renew when the cert is within this many days of expiry.
`check_interval`	`6h`	How often the renewal thread wakes to check.
`renew_timeout`	—	How long to wait for the platform to return a renewed certificate.

`modules`

The single list of modules Omega runs. There is exactly one list — required — and it means what it says.

modules:
  required:
    - ota
    - service-runtime

A module in required must be compiled into this binary. If it is not (its build feature is disabled), Omega fails to start with a precise error naming the module — it is never silently skipped.
Nothing auto-runs. Only modules listed here start. The build deciding a module can exist does not make it run; the profile must name it.
Module order does not need to be managed by hand — dependencies are resolved automatically.

Earlier versions of Omega had a second optional list whose modules were skipped when unavailable. That is gone — silent skipping hid real build/config mismatches. A legacy profile that still carries an optional: key parses (the key is ignored), but those modules will not run. Move anything you actually want to required.

Because a required module that isn’t compiled is fatal, the profile’s modules.required is effectively a manifest that the binary must satisfy — which is exactly the guarantee you want: an online device is one whose declared modules are all present.

`security`

Capability grants, control-message authentication, and resource quotas.

security:
  capabilities:
    ota: true
    service-runtime: true
  max_payload_bytes: 131072
  max_storage_bytes: 131072
  max_storage_item_bytes: 16384
  max_storage_bucket_items: 256
  signed_control:
    enabled: true
    key_env: OMEGA_SIGNING_KEY
    max_age: 60s
  rpc:
    allowed_commands:
      - hostname
      - uptime

`security.capabilities`

A map of capability → bool. A capability gates whether a module will accept control messages for its domain — a module can be running but reject every command if its capability is not granted (true). Two rules make this predictable:

A granted capability must be available in this build. If you set some-cap: true but nothing in the binary provides some-cap, Omega fails to start with an exact error (security.capabilities enables "some-cap" but it is not available in this build…). Capabilities are validated against what is compiled, so there is no separate list to keep in sync with the build.
A grant for a module that isn’t in modules.required is reported as inert (a warning) — the grant does nothing because the module isn’t running.

Most capability names are module names (ota, rpc, device-control, …). A few are provided internally by the ota module rather than being standalone modules — inventory and node — and are valid whenever ota is compiled.

Control-message signing — `security.signed_control`

Field	Description
`enabled`	Require every control message to carry a valid signature.
`key` / `key_env`	The signing key, inline or (preferred) from an environment variable.
`max_age`	Reject messages older than this (replay protection).

Resource quotas

Field	Meaning
`max_payload_bytes`	Maximum size of a single MQTT publish. Must fit within the broker’s and platform’s packet-size limits — a report larger than the smallest limit on the path is dropped, so align this with your broker’s `max_packet_size`.
`max_storage_bytes`	Total on-device storage budget for the storage backend.
`max_storage_item_bytes`	Maximum size of a single stored item.
`max_storage_bucket_items`	Maximum items per storage bucket.
`expose_sensitive_telemetry`	Default `false`. When false, telemetry that could carry identifying data is redacted before it leaves the device.

Shell command allowlist — `security.rpc.allowed_commands`

The rpc (and remote-command) capability runs only programs on this allowlist. An empty list denies everything. Keep it as narrow as the device actually needs — a broad allowlist is effectively remote shell.

Environment overrides

Almost every string field in connection has a <field>_env twin that reads the value from an environment variable instead of hard-coding it in the file. For example server_url / server_url_env, device_id / device_id_env, tls.client_key_path / tls.client_key_path_env. Prefer the _env form for secrets and per-device values so the profile itself stays free of machine-specific state. A few behaviors are driven by process environment variables rather than the profile:

Variable	Effect
`OMEGA_KEY_PREFERENCE`	`prefer_hardware` (default), `require_hardware`, or `software_only` — chooses the device-key backend. `require_hardware` refuses to start on a device with no usable hardware key store.
`OMEGA_LOG_FILE`	Mirror the log stream to a file (a service has no console).
`OMEGA_LOG_MQTT`	Verbose MQTT event logging for debugging.

Validation

Validate a profile without starting the device:

omega-agent --validate --client /path/to/config.yaml

Exit 0 and ✓ config valid — the profile parses and every module and capability it names is present in this binary.
Exit 1 with one ERROR: line per problem — validation collects all errors, each naming the exact field and cause, e.g.:

ERROR: required module "rpc" is not available: it is not implemented, or its build feature is disabled in this binary
ERROR: security.capabilities enables "device-control" but it is not available in this build: its module's feature is disabled, or the capability name is unknown

The same validation runs at boot and when a new profile arrives over the air, so a config error is caught before it can affect a running fleet. There are no silent failures: a profile problem is always fatal and always names what to fix.

What happens on a bad profile at startup

If the profile is malformed or names something the binary can’t provide, Omega does not come up half-working. It:

writes the exact reason to logs/startup-error.log (and, on Windows, the Application Event Log),
exits with a distinct code (78), and
the service supervisor stops the service cleanly with that reason surfaced — so an operator sees what is wrong instead of a generic “service failed to start.”

The rule across the board: bad config, an uncompiled module, an ungranted capability, and a broker-denied topic all fail fatally with the exact reason recorded durably. Transient conditions (broker unreachable) retry; anything a human must fix stops loudly.

Writing a profile from scratch

Start from identity

Set name, and the connection block: transport, server_url, device_id, root_topic, and cert_dir. These are the fields that make the device reachable.

Point TLS at the certificates

Fill connection.mqtt.tls with the CA bundle and the device cert/key paths — or, for a fresh device, add a connection.jitr block so it enrolls on first boot and writes its own cert into cert_dir.

List the modules you want to run

Add each module to modules.required. Every one must be compiled into the binary you deploy — check with omega-agent --validate.

Grant the matching capabilities

For each module that accepts control messages, add security.capabilities.<module>: true. Validation will tell you immediately if a grant references something the build doesn’t have.

Set quotas and signing

Set max_payload_bytes to fit your broker’s packet limit, and enable signed_control for authenticated control.

Validate before you ship

omega-agent --validate --client config.yaml — fix every ERROR: line until it prints ✓ config valid.

Minimal profile

The smallest profile that boots, enrolls, and stays managed:

name: my-device
platform: linux

connection:
  transport: mqtts
  server_url: mqtts://broker.example.golain.io:8883
  device_id: my-device
  root_topic: /myorg/my-device
  cert_dir: /var/lib/omega/certs
  mqtt:
    keep_alive: 30s
    tls:
      ca_cert_path: /var/lib/omega/certs/ca.pem
      client_cert_path: /var/lib/omega/certs/device.crt
      client_key_path: /var/lib/omega/certs/device.key

modules:
  required:
    - ota
    - service-runtime

Fuller profile

Adds enrollment, renewal, a capability grant, signed control, and quotas:

name: my-device
platform: linux

connection:
  transport: mqtts
  server_url: mqtts://broker.example.golain.io:8883
  device_id: my-device
  root_topic: /myorg/my-device
  cert_dir: /var/lib/omega/certs
  mqtt:
    keep_alive: 30s
    clean_session: true
    tls:
      ca_cert_path: /var/lib/omega/certs/ca.pem
      client_cert_path: /var/lib/omega/certs/device.crt
      client_key_path: /var/lib/omega/certs/device.key
  cert_renewal:
    enabled: true
    renew_window_days: 30
    check_interval: 6h

modules:
  required:
    - ota
    - service-runtime
    - metadata

security:
  capabilities:
    ota: true
    service-runtime: true
    metadata: true
  max_payload_bytes: 32768
  signed_control:
    enabled: true
    key_env: OMEGA_SIGNING_KEY
    max_age: 60s

Common pitfalls

Module listed in required but not compiled into the binary

Fatal at startup with required module "X" is not available…. Either build a binary that includes that module’s feature, or remove it from modules.required. Run omega-agent --validate to catch it before deploying.

Capability granted but its module isn't compiled

Fatal with security.capabilities enables "X" but it is not available in this build. Capabilities are validated against the build — remove the grant or add the feature.

Reports never reach the platform

Usually max_payload_bytes set larger than the broker or platform accepts, so large publishes are dropped in transit while small ones get through. Align it with the smallest packet-size limit on the path.

Device comes up but rejects every command

The module is running but its security.capabilities.<module> grant is missing or false. Grant it (true).

Omega edge runtime

Device RPC

Edge SQLite sync

Edge agent (Omega)

Operate & query

Wire protocol reference

Configure Omega

The mental model: build vs. profile

The build decides what is POSSIBLE

The profile decides what RUNS

Where the profile lives and how it loads

Top-level structure

`connection`

`connection.mqtt`

`connection.mqtt.tls`

`connection.jitr` — enrollment

`connection.cert_renewal`

`modules`

`security`

`security.capabilities`

Control-message signing — `security.signed_control`

Resource quotas

Shell command allowlist — `security.rpc.allowed_commands`

Environment overrides

Validation

What happens on a bad profile at startup

Writing a profile from scratch

Minimal profile

Fuller profile

Common pitfalls

See also

​The mental model: build vs. profile

The build decides what is POSSIBLE

The profile decides what RUNS

​Where the profile lives and how it loads

​Top-level structure

​connection

​connection.mqtt

​connection.mqtt.tls

​connection.jitr — enrollment

​connection.cert_renewal

​modules

​security

​security.capabilities

​Control-message signing — security.signed_control

​Resource quotas

​Shell command allowlist — security.rpc.allowed_commands

​Environment overrides

​Validation

​What happens on a bad profile at startup

​Writing a profile from scratch

​Minimal profile

​Fuller profile

​Common pitfalls

​See also

The mental model: build vs. profile

Where the profile lives and how it loads

Top-level structure

`connection`

`connection.mqtt`

`connection.mqtt.tls`

`connection.jitr` — enrollment

`connection.cert_renewal`

`modules`

`security`

`security.capabilities`

Control-message signing — `security.signed_control`

Resource quotas

Shell command allowlist — `security.rpc.allowed_commands`

Environment overrides

Validation

What happens on a bad profile at startup

Writing a profile from scratch

Minimal profile

Fuller profile

Common pitfalls

See also