Configuration reference

The agent's configuration is a single EdgeSettings. You fill it from a YAML (or JSON) file and environment variables.

Precedence: environment variables > file > defaults#

When the same key is set in several places, the environment variable wins. This order supports a layout where secrets such as the token live in /etc/geo-mlops/edge.env and the site setup (collectors, addresses, retention limits) lives in edge.yaml. You can rotate the token without touching the YAML.

Config file lookup order#

Without --config, the agent looks in this order and reads only the first file it finds.

1. The file that the GEO_EDGE_CONFIG environment variable points to — if it is set, the search stops here. If that file does not exist, it does not look anywhere else and starts with defaults.
2. /etc/geo-mlops/edge.yaml
3. edge.yaml in the current directory

The agent starts with defaults even when there is no file at all. In that case central is empty, so the link stays offline and data only accumulates locally. Check the values actually applied with geo-mlops-edge config.

Environment variables#

Put the key name in upper case after the GEO_EDGE_ prefix, and join nested keys with a double underscore (__).

GEO_EDGE_CENTRAL__BASE_URL=https://mlops.example.com
GEO_EDGE_CENTRAL__TOKEN=<device-token>
GEO_EDGE_DATA_DIR=/var/lib/geo-mlops-edge
GEO_EDGE_API__TOKEN=<your-secret>
GEO_EDGE_RETENTION__MAX_BYTES=100GiB
GEO_EDGE_LOG_LEVEL=DEBUG

Lists (collectors, sync.windows, api.cors_origins) are better written in the file. To pass them as environment variables they must be JSON strings (GEO_EDGE_SYNC__WINDOWS='["22:00-06:00"]').

Size strings#

Size fields accept strings such as 50GiB instead of an integer byte count. Case does not matter.

Applies to: retention.max_bytes, retention.free_disk_min_bytes, sync.chunk_bytes, sync.max_bytes_per_s, api.max_body_bytes, and the http collector's max_body_bytes.

All fields#

Top level#

central#

The agent talks to Central only when both base_url and token are set.

device#

retention — local retention limits#

Whichever of the three is hit first wins. When exceeded, items are dropped lowest priority first, and oldest first within the same priority.

sync — upload throttling#

link — link monitoring#

Factory links flap often, so these two counters keep a single lucky success from starting a transfer of tens of GB.

api — local HTTP API#

models — model cache#

Full example#

central:
  base_url: https://mlops.example.com
  timeout_s: 10
  verify_tls: true

device:
  id: edge-line-01
  location: line-1

data_dir: /var/lib/geo-mlops-edge

retention:
  max_bytes: 50GiB
  max_age_days: 30
  free_disk_min_bytes: 5GiB

sync:
  batch_size: 500
  chunk_bytes: 32MiB
  max_bytes_per_s: 0
  cpu_pause_percent: 85
  windows: []
  urgent_priority: 90

link:
  probe_interval_s: 5
  backoff_max_s: 60
  online_after_ok: 2
  offline_after_fail: 3

heartbeat_interval_s: 30
commands_poll_s: 25

api:
  enabled: true
  host: 0.0.0.0
  port: 8600
  token: ""
  max_body_bytes: 2GiB

models:
  keep_versions: 2

policy_source: central
log_level: INFO

collectors: []   # see the Data collectors page