Omega setup for SQLite sync

Omega ships a production reference client ilyama-edge for Golain SQLite replication. This page covers install paths, environment, and first run.

Fastest path: golain scaffold

If you have golain installed and a registered device:

golain login
golain context set --org=my-org --project=my-project

golain omega scaffold \
  --device=gw-floor-2 \
  --fleet=sensors \
  --sample-db \
  --transport=tls \
  --verify-tables

This command:

Issues or reuses MQTT mTLS certificates
Seeds a sample SQLite DB, or a three-table verification DB when you pass --verify-tables (vrf_*_events, vrf_*_state, vrf_*_metrics)
Downloads Omega and SQLite deps from https://tools.ilyama.golain.io/omega/
Writes omega-config.yaml, omega-env.sh, and replication triggers

Run:

source ~/.config/golain/omega/gw-floor-2/omega-env.sh
~/.config/golain/omega/gw-floor-2/omega \
  -client ~/.config/golain/omega/gw-floor-2/omega-config.yaml

Or use the TUI Deploy Omega wizard (O on device detail). → Omega deploy

Prefer --transport=tls when QUIC is unavailable. Some brokers reject QUIC; TLS (ssl://host:8883) is the reliable default for first connect.

Manual install (CDN)

When not using scaffold:

curl -fsSL https://tools.ilyama.golain.io/omega/install.sh | sh
curl -fsSL https://tools.ilyama.golain.io/omega/install-sqlite-deps.sh | sh

→ Install Omega

Prerequisites

Device registered in Golain (fleets and devices)
mTLS certificate issued for MQTT (scaffold does this automatically; see provisioning checklist for manual flow)
Application SQLite database path on the device
Network path to MQTT broker (TLS TCP or QUIC)

Build from source (development)

Client-specific binary (production)

Embeds connection config and only required modules:

git clone https://github.com/golain-io/omega
cd omega
make build-client CLIENT=ilyama-edge GOOS=linux GOARCH=arm64
# → bin/omega-linux-arm64

Development run from source

make build
go run ./cmd/omega -client clients/ilyama-edge-dev.yaml

ilyama-edge-dev.yaml adds macOS support and explicit state_db_path_env.

Reference client YAML

Scaffold generates a profile equivalent to clients/ilyama-edge.yaml:

name: ilyama-edge
platform: linux
connection:
  transport: mqtt
  server_url_env: OMEGA_MQTT_BROKER_URL
  device_id_env: OMEGA_DEVICE_ID
  root_topic_env: OMEGA_ROOT_TOPIC
  mqtt:
    keep_alive: 30s
    clean_session: false
    tls:
      ca_cert_path_env: OMEGA_TLS_CA_PATH
      client_cert_path_env: OMEGA_TLS_CERT_PATH
      client_key_path_env: OMEGA_TLS_KEY_PATH

modules:
  required:
    - sqlite-replication
    - heartbeat

security:
  auth_token_env: OMEGA_AUTH_TOKEN
  signed_control:
    enabled: true
  capabilities:
    sqlite-replication: true
    heartbeat: true

sqlite-replication:
  source_db_path_env: OMEGA_SOURCE_DB_PATH
  flush_interval: 5s

→ Full field reference: Configuration

Environment variables

Variable	Purpose
`OMEGA_MQTT_BROKER_URL`	e.g. `ssl://mqtt.example.com:8883` or `quic://host:port`
`OMEGA_DEVICE_ID`	Device name (must match Golain registration / MQTT client id)
`OMEGA_ROOT_TOPIC`	`{topic_slug}/{device_name}` or `/{device_name}` if no slug
`OMEGA_SOURCE_DB_PATH`	Path to application SQLite file
`OMEGA_STATE_DB_PATH`	Persistent cursors/pause state (recommended prod)
`OMEGA_TLS_CA_PATH`	Broker CA PEM
`OMEGA_TLS_CERT_PATH`	Device client cert PEM
`OMEGA_TLS_KEY_PATH`	Device client key PEM
`OMEGA_AUTH_TOKEN`	Control message auth (HMAC envelope)

Example block (also generated in omega-env.sh):

export OMEGA_MQTT_BROKER_URL=ssl://mqtt.ilyama.golain.io:8883
export OMEGA_DEVICE_ID=gw-floor-2
export OMEGA_ROOT_TOPIC=acme-prod/gw-floor-2
export OMEGA_SOURCE_DB_PATH=/var/lib/myapp/data.db
export OMEGA_STATE_DB_PATH=/var/lib/omega/state.db
export OMEGA_TLS_CA_PATH=/etc/omega/ca.pem
export OMEGA_TLS_CERT_PATH=/etc/omega/device.pem
export OMEGA_TLS_KEY_PATH=/etc/omega/device.key
export OMEGA_AUTH_TOKEN=<from-provisioning>
./omega-linux-arm64

Sample multi-table dev setup

When building Omega from source without scaffold:

bash scripts/seed-sample-replication-db.sh
go run ./cmd/omega -client clients/ilyama-edge-sample.yaml
# second terminal — mutations after omega installed triggers:
bash scripts/sample-replication-mutations.sh

Tables: order_events, device_state, sensor_timeseries. Use rows for relational/state tables and telemetry for time-series tables with a stable timestamp column.

Multi-table verification with `--verify-tables`

golain omega scaffold --verify-tables creates three uniquely named SQLite tables so you can validate a fresh end-to-end sync without colliding with existing lineages in a shared Project:

vrf_<suffix>_events — row-batch verification
vrf_<suffix>_state — relational/state verification
vrf_<suffix>_metrics — telemetry verification

This is the fastest way to confirm the full current Omega + ilyama flow:

Scaffold with --verify-tables
Start Omega
Approve the queued review in Edge Sync
Confirm all three lineages appear for the device
Read telemetry from the Project-scoped edge_ts_* hypertable for vrf_<suffix>_metrics

Verify cloud ingest

Console or golain devices get — device connected.
golain TUI → Edge Sync → Lineages — lineages appear per table. With --verify-tables, expect three lineages for the device.
Expect schema review queued on first batch — approve workflow.
After approval, expect telemetry for the vrf_*_metrics table in the Project’s edge_ts_* hypertable and relational rows for vrf_*_state through mirror-rows.

Maintainer e2e script (ilyama):

cd ilyama/tools/platform-tui
./scripts/verify-omega-scaffold.sh

Deploy as service

→ Deploy Omega (systemd / launchd / Windows)

Automated deployed e2e (maintainers)

echo '<bearer-token>' > .e2e-deployed/bearer.token
bash scripts/run-deployed-replication-e2e.sh

Details: omega deployed-e2e-provisioning.

Omega edge runtime

Device RPC

Edge SQLite sync

Edge agent (Omega)

Operate & query

Wire protocol reference

Omega setup for SQLite sync

Fastest path: golain scaffold

Manual install (CDN)

Prerequisites

Build from source (development)

Client-specific binary (production)

Development run from source

Reference client YAML

Environment variables

Sample multi-table dev setup

Multi-table verification with `--verify-tables`

Verify cloud ingest

Deploy as service

Automated deployed e2e (maintainers)

​Fastest path: golain scaffold

​Manual install (CDN)

​Prerequisites

​Build from source (development)

​Client-specific binary (production)

​Development run from source

​Reference client YAML

​Environment variables

​Sample multi-table dev setup

​Multi-table verification with --verify-tables

​Verify cloud ingest

​Deploy as service

​Automated deployed e2e (maintainers)

​Related

Fastest path: golain scaffold

Manual install (CDN)

Prerequisites

Build from source (development)

Client-specific binary (production)

Development run from source

Reference client YAML

Environment variables

Sample multi-table dev setup

Multi-table verification with `--verify-tables`

Verify cloud ingest

Deploy as service

Automated deployed e2e (maintainers)

Related