viam-agent reference | Viam Documentation
viam-agent reference
viam-agent is the on-device service manager for Viam. It runs as a systemd service on Linux machines and handles four responsibilities:
- Managing
viam-server: downloading, installing, starting, and restartingviam-serveras versions change. - Provisioning: creating a WiFi hotspot or Bluetooth service on first boot so end users can provide network credentials and connect the machine to Viam Cloud.
- System configuration: managing OS-level settings like automatic package updates and log forwarding.
- Network management: configuring WiFi networks, monitoring connectivity, and re-entering provisioning mode when connectivity is lost.
viam-agent polls Viam Cloud on a regular interval (minimum 5 seconds, configurable by the cloud) for configuration updates. When the cloud sends new settings, viam-agent applies them locally.
Installation
The Viam app generates a machine-specific install command on each machine’s setup page. The command downloads viam-agent, registers the machine with Viam Cloud, and configures the systemd service:
sudo /bin/sh -c "VIAM_API_KEY_ID=<KEYID> VIAM_API_KEY=<KEY> VIAM_PART_ID=<PARTID>; $(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)"
Copy this command from the CONNECT tab on your machine’s page in the Viam app. Do not construct it by hand.
For manufacturing and fleet provisioning (installing onto device images before first boot), use the preinstall script instead. See Provision devices for the full workflow.
How updates work
When the cloud sends a new version for viam-agent or viam-server, the agent:
- Downloads the new binary to a local cache directory.
- Validates the download against the expected SHA-256 checksum.
- Swaps the running binary using an atomic symlink operation. The old binary remains cached for 30 days.
If power is lost during download, viam-agent discards the incomplete file and re-downloads on the next check cycle. The currently running binary is never interrupted during the download or validation steps.
viam-agent does not automatically roll back to a previous version if the new version fails to start. If a deployed version crashes on startup, viam-agent will keep retrying that version until you change the cloud config to pin an older one.
Version control
Control which versions of viam-agent and viam-server run on the machine.
In the machine settings card in the Viam app, open Settings and expand Software Updates:
- Agent version: choose
stable(the default, tracks the latest stable release), a specific semver release such as5.6.77, or a URL to a custom binary. - viam-server version: same options as agent.
When you change a version, the cloud sends an update instruction to viam-agent on the machine’s next check cycle. The agent downloads and installs the new binary using the atomic swap mechanism described above.
Changing the viam-server version takes effect on the next maintenance window (if configured) or immediately. Changing the viam-agent version requires restarting viam-agent to take effect. See Restart viam-agent.
To control when updates are applied, configure a maintenance window. To stage rollouts across a fleet, use fragment tags.
Advanced settings
In the machine settings card, open Settings and expand Advanced:
| Field | Type | Default | Description |
|---|---|---|---|
debug |
boolean | false |
Enable debug logging for viam-agent. |
wait_for_update_check |
boolean | false |
Wait for a network connection and update check before starting viam-server. Useful for ensuring the latest version runs on boot. |
disable_viam_server |
boolean | false |
Prevent viam-agent from starting viam-server. For development use. |
disable_network_configuration |
boolean | false |
Disable viam-agent’s network and hotspot management. |
disable_system_configuration |
boolean | false |
Disable viam-agent’s system configuration management (OS updates, log forwarding). |
viam_server_start_timeout_minutes |
integer | 10 |
Minutes to wait before restarting an unresponsive viam-server. |
viam_server_env |
object | {} |
Environment variables passed to viam-server and all modules. |
disable_log_deduplication |
boolean | false |
Disable log deduplication for viam-agent. By default, viam-agent collapses noisy log messages (those that repeat more than 3 times within one minute) into a single message with a repeat count. Set to true to print every log line. |
System configuration
In the machine settings card, open Settings and expand System:
OS package updates
| Field | Type | Default | Description |
|---|---|---|---|
os_auto_upgrade_type |
string | "" |
Controls automatic OS package updates. Accepts "all", "security", "managed-all", "managed-security", "disable", or "" (leave OS defaults). The modes are described below. |
os_managed_upgrade_interval_hours |
float | 24 |
How often viam-agent checks for and installs packages, in hours. Minimum value: 1. Only applies when os_auto_upgrade_type is "managed-all" or "managed-security". |
The "all" and "security" modes delegate scheduling to the operating system’s built-in upgrade timer (unattended-upgrades on Debian). The "managed-all" and "managed-security" modes let viam-agent control the upgrade schedule directly, which also enables upgrade support on Ubuntu and RPM-based distributions (Fedora, RHEL, Rocky Linux, AlmaLinux, CentOS).
When using a managed mode, viam-agent disables the OS’s built-in upgrade timer and runs upgrades itself at the configured interval. If an upgrade requires a reboot, viam-agent waits until the configured maintenance window before rebooting the machine.
| Mode | Supported distributions | Schedule controlled by | Reboot coordination |
|---|---|---|---|
"all", "security" |
Debian, Raspberry Pi OS (Bullseye, Bookworm, or Trixie) | OS (unattended-upgrades) |
None |
"managed-all", "managed-security" |
Debian, Ubuntu, Raspberry Pi OS, Fedora, RHEL 7+, Rocky, AlmaLinux, CentOS 7 (apt and RPM), and Windows (PSWindowsUpdate) | viam-agent |
Waits for maintenance window |
The "all" and "security" modes require Debian (including Debian-based systems like Raspberry Pi OS) with the Bullseye, Bookworm, or Trixie release codename. On Ubuntu, an RPM-based distribution, or Windows, use a managed mode instead. On Windows, managed modes use the PSWindowsUpdate PowerShell module. When a selected mode is not supported on the running OS, the agent logs a warning and the setting has no effect.
Log forwarding
| Field | Type | Default | Description |
|---|---|---|---|
forward_system_logs |
string | "" |
Forward operating system logs to Viam’s cloud log viewer. Options: "all" (forward all system logs), a comma-separated list of service identifiers (forward only those services), or prefix a service with - to exclude it. For example, "all,-gdm,-tailscaled" forwards everything except gdm and tailscaled. |
logging_journald_system_max_use_megabytes |
integer | 512 |
Maximum disk space for persistent system journal logs, in megabytes. Set to -1 to disable the limit. |
logging_journald_runtime_max_use_megabytes |
integer | 512 |
Maximum disk space for runtime (volatile) journal logs, in megabytes. Set to -1 to disable the limit. |
logging_journald_storage |
string | "persistent" |
Controls how system logs (journald) are stored locally. Options: "persistent" (store on disk in /var/log/journal, persists across reboots), "volatile" (store in memory in /run/log/journal, deleted on reboot), "auto" (persistent if /var/log/journal exists, otherwise volatile), "none" (do not store any logs locally). |
Additional networks
Add WiFi or wired networks that the machine can connect to. Each network has a name and connection settings you configure individually.
In the machine settings card, open Settings and expand Known Networks. Click Add another network and configure:
| Field | Type | Default | Description |
|---|---|---|---|
type |
string | "wifi", "wired", or "bluetooth" (for Bluetooth tethering connections). |
|
ssid |
string | The WiFi network name. Required for WiFi networks. | |
psk |
string | The WiFi password. | |
priority |
integer | 0 |
Network selection priority. Higher values win. Set higher than the current network’s priority if you want the machine to prefer this one. |
interface |
string | The network interface to use (for example, wlan0, eth0). Leave empty to use the default. |
|
ipv4_address |
string | "auto" |
Static IPv4 address in CIDR notation, or "auto" for DHCP. |
ipv4_gateway |
string | Gateway address for static IP configuration. | |
ipv4_dns |
array | [] |
DNS server addresses for static IP configuration. |
ipv4_route_metric |
integer | 0 |
Route metric for this network. Lower values are preferred. When set to 0, the OS applies its own defaults (typically 100 for wired, 600 for wireless). |
For provisioning-time network setup, add networks to the additional_networks section of the defaults file. See Provision devices.
Restart viam-agent
After changing the viam-agent version or modifying settings that require a restart, restart the service:
sudo systemctl restart viam-agent
To check whether viam-agent is running:
sudo systemctl status viam-agent
To view viam-agent logs:
sudo journalctl -u viam-agent -f
When you restart viam-agent, viam-server also restarts. Rebooting the machine has the same effect.