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

   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_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.

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.