Configuration reference | MLOps Central Platform Manual

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. Keep secrets such as the token in /etc/geo-mlops/edge.env and the site setup (collectors, addresses, retention limits) in edge.yaml. Then rotating the token leaves the YAML untouched.

With policy_source: central (the default), Central's policy comes before the file. A device whose policy has been saved on Central at least once (revision 1 or later) receives that policy on its first heartbeat after start and replaces heartbeat_interval_s, commands_poll_s, retention and sync as a whole. Items not edited on the screen are also replaced, with the server's default policy values. To keep the file values, set policy_source: local (Commands, policy and retention).

Config file lookup order

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

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.
/etc/geo-mlops/edge.yaml
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) belong 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.

Unit	Multiplier	Unit	Multiplier
`B`	1
`KB`	1000	`KiB`	1024
`MB`	1000²	`MiB`	1024²
`GB`	1000³	`GiB`	1024³
`TB`	1000⁴	`TiB`	1024⁴

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

Key	Default	Description
`central`	(below)	Connection to the central server
`device`	(below)	Device name and location
`data_dir`	`/var/lib/geo-mlops-edge`	Holds the queue DB (`edge.db`), the file spool (`spool/`) and the model cache (`models/`)
`disk_path`	`""`	Filesystem whose disk usage is measured and on which retention limits are enforced. Empty means `data_dir`
`heartbeat_interval_s`	`30`	Heartbeat interval (seconds)
`commands_poll_s`	`25`	Command long-poll wait time (seconds)
`retention`	(below)	Local retention limits
`sync`	(below)	Upload throttling
`link`	(below)	Link monitoring
`api`	(below)	Local HTTP API
`collectors`	`[]`	Collector list — Data collectors
`models`	(below)	Model cache
`policy_source`	`central`	With `central`, the policy sent by Central overrides `heartbeat_interval_s`, `commands_poll_s`, `retention` and `sync`. With `local`, this file wins
`log_level`	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR`

`central`

Key	Default	Description
`base_url`	`""`	Central API address (`https://mlops.example.com`). Empty means offline only
`token`	`""`	Device token. Pass it through the `GEO_EDGE_CENTRAL__TOKEN` environment variable (the file is read too, but files easily end up in repositories and backups)
`timeout_s`	`10.0`	Request timeout (seconds)
`verify_tls`	`true`	TLS certificate verification

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

`device`

Key	Default	Description
`id`	`""`	Device name. Empty means the host name, or if that is missing too, `edge-<first 8 characters of the machine ID>`. Characters other than letters, digits, `.`, `_` and `-` become `-`, and it is cut at 64 characters
`location`	none	Location reported to Central at registration. If set, it replaces the location on Central at every registration. If empty, the Central value is left alone

`retention` — local retention limits

Hitting any one of the three triggers cleanup. Items older than max_age_days are dropped regardless of priority. When max_bytes or free_disk_min_bytes is exceeded, items are dropped lowest priority first, and oldest first within the same priority. Items being sent right now are never dropped. Cleanup runs when the agent starts and whenever a collector or the local API (/records, /blobs, push) adds a new item.

Key	Default	Description
`max_bytes`	`50GiB`	Upper limit on total queue size
`max_age_days`	`30`	Items queued longer ago than this are dropped. `0` means no age limit
`free_disk_min_bytes`	`5GiB`	When free disk space falls below this, items are dropped to make room. `0` disables the check

`sync` — upload throttling

Key	Default	Description
`batch_size`	`500`	Records per request (server limit 1000)
`chunk_bytes`	`32MiB`	Requested file chunk size. The actual size is the value the server decides and returns
`max_bytes_per_s`	`0`	Upload rate limit. `0` means unlimited
`cpu_pause_percent`	`85`	Pauses uploads when system CPU is at or above this value. `0` disables the check
`windows`	`[]`	Allowed upload windows (device local time; in a container, the container's time zone), for example `["22:00-06:00"]`. Empty means always
`concurrency`	`1`	Files sent after each record batch. Files are sent one at a time, not in parallel
`urgent_priority`	`90`	Items at this priority or above ignore `windows` and are sent

`link` — link monitoring

Key	Default	Description
`probe_interval_s`	`5.0`	How often Central's `/api/v1/health` is probed
`backoff_max_s`	`60.0`	Upper limit on the interval as it grows during repeated failures
`online_after_ok`	`2`	How many successes in a row count as `online`
`offline_after_fail`	`3`	How many failures in a row count as `offline`

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

Key	Default	Description
`enabled`	`true`	Whether to start the local API
`host`	`0.0.0.0`	Bind address. `127.0.0.1` on a development PC
`port`	`8600`	Port
`token`	`""`	Empty means no authentication. If set, callers must send it in the `X-Edge-Api-Token` header
`cors_origins`	`["*"]`	Allowed browser origins
`max_body_bytes`	`2GiB`	Request body limit. Exceeding it gives 413. `0` disables the check

`models` — model cache

Key	Default	Description
`keep_versions`	`2`	Versions kept on disk per model. On every pull, the highest version numbers are kept up to this count and the rest are deleted. `0` means unlimited
`auto_activate`	`Production`	The setting exists, but the runtime does not read it. Automatic activation is covered in Models and inference

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

Precedence: environment variables > file > defaults#

Config file lookup order#

Environment variables#

Size strings#

All fields#

Top level#

central#

device#

retention — local retention limits#

sync — upload throttling#

link — link monitoring#

api — local HTTP API#

models — model cache#

Full example#