viam-agent

The viam-agent is a self-updating service manager that maintains the lifecycle for itself and viam-server.

Among other things, viam-agent:

• Installs, runs, and monitors viam-server or a custom build of viam-server.
• Provides tooling for device provisioning and network management.
• Provides automatic updates for viam-server and the agent itself.
• Allows control of deployed software versions through the Viam app.
• Provides various operating system settings.

To provision machines using viam-agent, see Provision Machines.

Installation

1

Add a new machine in the Viam app.

2

Navigate to the machine’s CONFIGURE tab.

3

Click View setup instructions on the alert to Set up your machine part:

4

Follow the instructions to install viam server with viam-agent.

Important

If you are using Linux, your machine must have curl available in order to install viam-agent.

You can use viam-agent either with an existing machine’s part ID and API key, or with an existing machine credentials file at /etc/viam.json.

The command will be of the following form:

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)"

Note

As an alternative to specifying the VIAM_API_KEY_ID, the VIAM_API_KEY, and the VIAM_PART_ID when running the command, you can also copy the machine cloud credentials from the Viam app into /etc/viam.json. You can get the machine cloud credentials by clicking the copy icon next to Machine cloud credentials in the part status dropdown to the right of your machine’s name on the top of the page.

Then run the following command to install viam-agent:

sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)"

On Linux, viam-agent will install itself as a systemd service named viam-agent. For information on managing the service, see Manage viam-agent.

Configuration

{
  "agent": {
    "version_control": {
      "agent": "stable",
      "viam-server": "0.52.1"
    },
    "advanced_settings": {
      "debug": false,
      "wait_for_update_check": false,
      "viam_server_start_timeout_minutes": 10,
      "disable_viam_server": false,
      "disable_network_configuration": false,
      "disable_system_configuration": false
    },
    "network_configuration": {
      "manufacturer": "viam",
      "model": "custom",
      "fragment_id": "",
      "hotspot_interface": "wlan0",
      "hotspot_prefix": "viam-setup",
      "hotspot_password": "viamsetup",
      "disable_captive_portal_redirect": false,
      "offline_before_starting_hotspot_minutes": 2,
      "user_idle_minutes": 5,
      "retry_connection_timeout_minutes": 10,
      "turn_on_hotspot_if_wifi_has_no_internet": false,
      "wifi_power_save": null
    },
    "additional_networks": {
      "network1": {
        "type": "wifi",
        "interface": "",
        "ssid": "fallbackNetOne",
        "psk": "myFirstPassword",
        "priority": 30,
        "ipv4_address": "",
        "ipv4_gateway": "",
        "ipv4_dns": [],
        "ipv4_route_metric": 0
      },
      "network2": {
        "type": "wifi",
        "interface": "",
        "ssid": "fallbackNetTwo",
        "psk": "mySecondPassword",
        "priority": 10,
        "ipv4_address": "",
        "ipv4_gateway": "",
        "ipv4_dns": [],
        "ipv4_route_metric": 0
      }
    },
    "system_configuration": {
      "logging_journald_system_max_use_megabytes": 128,
      "logging_journald_runtime_max_use_megabytes": 96,
      "os_auto_upgrade_type": "all",
      "forward_system_logs": "all,-gdm,-tailscaled"
    }
  }
}

version_control: Version management for viam-agent and viam-server

By default, when a new version of viam-server becomes available, it will automatically download. When viam-agent next restarts, it installs and starts using the new version of viam-server. To ensure that updates only occur when your machines are ready, configure a maintenance window. With a configured maintenance window, viam-agent will restart and upgrade viam-server only when maintenance is allowed and when viam-server is not currently processing config changes.

For more information on managing viam-agent see Manage viam-agent.

Update or downgrade viam-server with viam-agent

1. Navigate to your machine’s CONFIGURE tab.
2. Click on machine settings on the left side of the page.
3. Change the specified viam-server version.
4. Save your configuration.

advanced_settings

Reduce startup time

You can set wait_for_update_check to false to bypass viam-agent waiting for a network connection to be established and checking for updates during initial startup. This will result in viam-server executing as quickly as possible.

This is useful if you have a device that often starts when offline or on a slow connection, and if having the latest version immediately after start isn’t required.

You can also start viam-agent in fast start mode by setting VIAM_AGENT_FAST_START=1 in your environment.

network_configuration

For more detailed instructions on what these settings do, see Provisioning.

additional_networks

For an already-online device, you can configure new WiFi or wired networks in the machine’s viam-agent configuration in the Viam app. It’s primarily useful for a machine that moves between different networks, so the machine can automatically connect when moved between locations.

To add additional networks add them using the JSON editor for your device’s config in the Viam app.

During provisioning, viam-agent will try to connect to each specified network in order of priority from highest to lowest. If the highest-priority network is not available (or, if turn_on_hotspot_if_wifi_has_no_internet is enabled, the machine can connect but internet is not available), viam-agent will then attempt to connect to the next-highest network, and so on until all configured networks have been tried.

system-configuration

For more detailed instructions, see Configure machine settings.

Agent logs

These log messages include viam-server stops and starts, the status of viam-agent, and any errors or warnings encountered during operation.

• App UI
• Command line on Linux

viam-agent writes log messages to the Viam app.

viam-agent only sends messages when your machine is online and connected to the internet. If your machine is offline, log messages are queued and are sent to the Viam app once your machine reconnects to the internet.

Navigate to the LOGS tab of your machine’s page in the Viam app.

Select from the Levels dropdown menu to filter the logs by severity level:

sudo journalctl --unit=viam-agent

Core options