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.

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
`-tag`	—	—	a device tag as `key=value`, repeatable, for fleet selectors

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: