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 devices

Provision a machine as it first comes online with a pre-defined configuration - in the factory or when the machine is taken into service.

Installation

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

1. The first step is to add a new machine in the Viam app.
2. Navigate to the CONFIGURE tab and find your machine’s card. An alert will be present directing you to Set up your machine part:

Click View setup instructions to open the setup instructions. Then navigate to the machine part’s setup and follow the instructions to install viam server with viam-agent.

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 viam-server app JSON configuration 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)"

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_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": {
      {
        "type": "",
        "interface": "",
        "ssid": "",
        "psk": "",
        "priority": 0,
        "ipv4_address": "",
        "ipv4_gateway": "",
        "ipv4_dns": [],
        "ipv4_route_metric": 0
      }
    },
    "system_configuration": {
      "logging_journald_system_max_use_megabytes": 512,
      "logging_journald_runtime_max_use_megabytes": 512,
      "os_auto_upgrade_type": "security"
    }
  }
}

{
  "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_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": {
      {
        "type": "wifi",
        "interface": "",
        "ssid": "fallbackNetOne",
        "psk": "myFirstPassword",
        "priority": 30,
        "ipv4_address": "",
        "ipv4_gateway": "",
        "ipv4_dns": [],
        "ipv4_route_metric": 0
      },
      {
        "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"
    }
  }
}

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.

Important

viam-agent does not update itself. You must restart viam-agent or reboot in order to use the new version. When you stop or restart viam-agent, the agent will stop or restart viam-server as well.

When viam-server updates itself, you must restart viam-server in order to use the new version. You can restart viam-server from the machine’s part status dropdown to the right of your machine’s name on its page in the Viam app.

For more information on managing viam-agent see:

Manage viam-agent

Control and manage the viam-agent systemd service.

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.

If turn_on_hotspot_if_wifi_has_no_internet is enabled, agent-provisioning 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 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

viam-agent writes log messages to the Viam app. You can find these messages on the LOGS tab of your machine’s page.

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.

These log messages include when viam-server is stopped and started, the status of viam-agent, and any errors or warnings encountered during operation.