Device agent

Configuration

The agent is configured with command-line flags, each of which has a matching environment variable so the same settings can live in the service unit's environment file. The installer fills in sensible values; this page documents what they mean so you can tune a fleet to its environment.

Connection and identity

These four settings are required for the agent to run at all. They give it its address to call home and its mutual-TLS identity.

Flag	Environment	Purpose
`-server`	`MESHANICS_SERVER`	fleet device API address (`host:port`)
`-cert`	`MESHANICS_CERT`	device certificate (PEM)
`-key`	`MESHANICS_KEY`	device private key (PEM)
`-ca`	`MESHANICS_CA`	CA bundle used to verify the server (PEM)

Enabling over-the-air updates

Updates are opt-in and verification-first. The agent enables OTA only when both of the following are provisioned; supplying one without the other is a configuration error and the agent refuses to start.

Flag	Environment	Purpose
`-artifact-server`	`MESHANICS_ARTIFACT_SERVER`	artifact server URL (`https://host:port`)
`-tuf-root`	`MESHANICS_TUF_ROOT`	the provisioned trust anchor for update metadata

There is no over-the-air update without that trust anchor. With it, every payload is verified against signed metadata before the agent touches it.

Enabling customer-authorized releases

Signed releases add a customer-controlled authorization layer above TUF. All four settings are required together. A device that receives a signed-release pointer without this local trust binding fails the assignment instead of falling back to the advisory fields.

Flag	Environment	Purpose
`-release-tenant`	`MESHANICS_RELEASE_TENANT`	accepted tenant UUID
`-release-product`	`MESHANICS_RELEASE_PRODUCT`	product ID assigned to this device
`-release-profile`	`MESHANICS_RELEASE_PROFILE`	exact signed compatibility profile
`-release-trust-dir`	`MESHANICS_RELEASE_TRUST_DIR`	directory of pinned Ed25519 authorizer public key PEM files

Keep this directory root-owned and distribute it through the enrollment or another controlled provisioning process. Only regular .pem files are loaded; directories and symbolic links are ignored. Key changes after enrollment are a device provisioning action, not an instruction from the control plane.

State and runtime

Flag	Environment	Default	Purpose
`-data-dir`	`MESHANICS_DATA_DIR`	`/var/lib/meshanics`	where downloaded artifacts and the metadata cache live
`-container-runtime`	`MESHANICS_CONTAINER_RUNTIME`	`auto`	runtime for container payloads: `auto`, `podman`, `docker`, `none`, or a path
`-operational-snapshot-interval`	`MESHANICS_OPERATIONAL_SNAPSHOT_INTERVAL`	`30s`	cadence for the cached bounded CPU, memory, data-filesystem and local-address snapshot
`-operational-addresses`	`MESHANICS_OPERATIONAL_ADDRESSES`	`true`	set to `false` to exclude assigned local addresses while retaining resource context
`-integrity-scan-interval`	`MESHANICS_INTEGRITY_SCAN_INTERVAL`	`15m`	background cadence for re-measuring supported active artifacts; use a longer interval where reading large models creates unacceptable I/O
`-rauc`	`MESHANICS_RAUC`	`false`	enable the RAUC system D-Bus adapter on a device image with an existing A/B layout, keyring and bootloader policy
`-tag`	-	-	a device tag as `key=value`, repeatable, for fleet selectors

Model quality telemetry

The current installer provisions the model-quality receiver automatically for OTA-capable Linux devices. The application integration remains optional: the receiver is idle until a local serving process calls the fail-open SDK.

Flag	Environment	Default	Purpose
`-ml-metrics-server`	`MESHANICS_ML_METRICS_SERVER`	unset	device REST base used to forward aggregate windows; setting it enables the local receiver
`-ml-socket`	`MESHANICS_ML_SOCKET`	`/run/meshanics/ml.sock`	Unix datagram socket used by local telemetry clients

For direct and gateway onboarding, do not set the metrics server by hand. The installer derives port 9445 from the enrolled device or gateway host and keeps the existing certificate and TLS server-name verification. See Model quality telemetry for the SDK contract and diagnostics.

Allowlists: locked down by default

A few capabilities - exec health probes, configuration-file placement, and reload actions - are dangerous to grant blindly, so the agent ships them disabled and refuses them until an operator names exactly what is permitted. A signed payload may only choose from within an allowlist; it can never widen one, and allowlisted commands are always executed directly with a fixed argument list, never through a shell - so a tampered payload cannot smuggle in arbitrary commands.

The specific allowlist flags for each capability are listed in the install reference. Leave them unset and the corresponding capability stays off.

Inspection flags

Two flags exit immediately and are useful for diagnostics:

-print-hw-profile prints the detected hardware profile as JSON and exits.
-version prints the agent version and exits.