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.
• Provides various operating system settings.

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

Installation

1

Add a new machine.

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. Your machine must have curl available in order to install viam-agent.

• Linux
• Windows

You can use viam-agent either with

• environment variables
• a machine credentials file

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

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

The machine credentials file must be at /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.

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

On Windows, the viam-agent installer installs viam-agent as a service. Your machine credentials file must be at \etc\viam.json.

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,
      "viam_server_env": {
        "CUSTOM_VAR": "value"
      }
    },
    "network_configuration": {
      "manufacturer": "viam",
      "model": "custom",
      "fragment_id": "",
      "hotspot_interface": "wlan0",
      "hotspot_prefix": "viam-setup",
      "hotspot_password": "viamsetup",
      "disable_captive_portal_redirect": false,
      "disable_bt_provisioning": false,
      "disable_wifi_provisioning": false,
      "bluetooth_trust_all": false,
      "offline_before_starting_hotspot_minutes": 2,
      "user_idle_minutes": 5,
      "retry_connection_timeout_minutes": 10,
      "turn_on_hotspot_if_wifi_has_no_internet": true,
      "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

Environment Variables for viam-server

You can configure environment variables for viam-server using the viam_server_env setting in advanced_settings. Environment variables set through viam_server_env are passed to viam-server and all child processes it launches, including modules. viam-server also inherits existing environment variables from viam-agent, such as HOME, PWD, TERM, PATH.

Changes to viam_server_env are the only changes that automatically trigger a viam-server restart. Changing other configuration options requires a manual restart unless you’ve also changed viam_server_env.

Example configurations

{
  "agent": {
    "advanced_settings": {
      "viam_server_env": {
        "PION_LOG_TRACE": "all", # Debug logging for WebRTC
        "HTTPS_PROXY": "socks5://proxy.example.com:1080", # SOCKS proxy
        "HTTP_PROXY": "socks5://proxy.example.com:1080",
        "CUSTOM_VAR": "value"
      }
    }
  }
}

To remove an environment variable, remove it from the viam_server_env object and save your configuration.

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

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
• Event Viewer on Windows

viam-agent writes log messages to Viam.

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 Viam once your machine reconnects to the internet.

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

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

sudo journalctl --unit=viam-agent

Open the Windows Event Viewer (eventvwr from the command line).

You will find the viam-agent logs under Windows Logs > Application on the Details tab

Core options