# 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 restarting `viam-server` as 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:

```sh
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](https://docs.viam.com/fleet/provision-devices/) for the full workflow.

## How updates work

When the cloud sends a new version for `viam-agent` or `viam-server`, the agent:

1. Downloads the new binary to a local cache directory.
2. Validates the download against the expected SHA-256 checksum.
3. 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 as `5.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](https://docs.viam.com/reference/viam-agent/#restart-viam-agent).

To control when updates are applied, configure a [maintenance window](https://docs.viam.com/fleet/manage-versions/#maintenance-windows). To stage rollouts across a fleet, use [fragment tags](https://docs.viam.com/fleet/manage-versions/#staged-rollouts-with-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](https://docs.viam.com/fleet/manage-versions/#maintenance-windows) 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](https://docs.viam.com/fleet/provision-devices/).

## Restart viam-agent

After changing the `viam-agent` version or modifying settings that require a restart, restart the service:

```sh
sudo systemctl restart viam-agent
```

To check whether `viam-agent` is running:

```sh
sudo systemctl status viam-agent
```

To view `viam-agent` logs:

```sh
sudo journalctl -u viam-agent -f
```

When you restart `viam-agent`, `viam-server` also restarts. Rebooting the machine has the same effect.