viam-agent

The viam-agent is a self-updating service manager that maintains the lifecycle for itself and the following system services:

• viam-server: the core of the machine
• agent-provisioning: device provisioning subsystem that can set up machine configs and manage WiFi networks. For more information see Provisioning.
• agent-syscfg: provides various operating system and system configuration tweaks

Among other things, viam-agent:

• Installs, runs, and monitors viam-server You can also use a custom build of viam-server, if needed.
• Provides automatic updates for viam-server, the agent itself, and any configured subsystems (such as the agent-provisioning subsystem).
• Allows control of deployed software versions through the Viam app.

To provision machines using viam-agent, see

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

• Config Builder
• JSON (Default)
• JSON Example

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Agent.

Edit and fill in the attributes as applicable.

{
  "agent": {
    "viam-agent": {
      "release_channel": "stable",
      "pin_version": "",
      "pin_url": ""
    },
    "viam-server": {
      "release_channel": "stable",
      "pin_version": "",
      "pin_url": "",
      "disable_subsystem": false,
      "attributes": {
        "fast_start": false
      }
    },
    "agent-provisioning": {
      "release_channel": "stable",
      "pin_version": "",
      "pin_url": "",
      "disable_subsystem": false,
      "networks": []
    },
    "agent-syscfg": {
      "release_channel": "stable",
      "pin_version": "",
      "pin_url": "",
      "disable_subsystem": false
    }
  }
}

{
  "agent": {
    "viam-agent": {
      "pin_version": "1.2.3"
    },
    "viam-server": {
      "attributes": {
        "fast_start": true
      }
    },
    "agent-provisioning": {
      "attributes": {
        "hotspot_password": "acme123",
        "networks": [
          {
            "type": "wifi",
            "ssid": "fallbackNetOne",
            "psk": "myFirstPassword",
            "priority": 30
          },
          {
            "type": "wifi",
            "ssid": "fallbackNetTwo",
            "psk": "mySecondPassword",
            "priority": 10
          }
        ]
      }
    },
    "agent-syscfg": {
      "attributes": {
        "logging": {
          "disable": true,
          "system_max_use": "128M",
          "runtime_max_use": "96M"
        },
        "upgrades": {
          "type": "all"
        }
      }
    }
  }
}

Each section primarily controls updates for that subsystem:

viam-agent

viam-server

Fast start mode

You can use fast start mode 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.

agent-provisioning

Networks

For an already-online device, you can add additional networks to the machine’s viam-agent configuration. It’s primarily useful for a machine that might move between different WiFi 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 roaming_mode 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.

The following configuration defines the connection information and credentials for two WiFi networks named fallbackNetOne and fallbackNetTwo:

...
"agent": {
  "agent-provisioning": {
    ...
    "attributes": {
      ...
      "roaming_mode": true,
      "networks": [
        {
          "type": "wifi",
          "ssid": "fallbackNetOne",
          "psk": "myFirstPassword",
          "priority": 30
        },
        {
          "type": "wifi",
          "ssid": "fallbackNetTwo",
          "psk": "mySecondPassword",
          "priority": 10
        }
      ]
    }
  }
}

agent-syscfg

agent-syscfg is a subsystem (plugin) for viam-agent that provides a number of system and operating system configuration helpers.

The following configuration allows all upgrades from configured sources and sets the maximum disk space journald will user for persistent log storage to 128MB and the runtime limit to 96MB:

"agent-syscfg": {
  "release_channel": "stable",
  "attributes": {
    "logging": {
      "disable": true,
      "system_max_use": "128M",
      "runtime_max_use": "96M"
    },
    "upgrades": {
      "type": "all"
    }
  }
}

Version management for viam-agent and viam-server

viam-agent automatically updates both itself, its subsystems, and viam-server as new updates are released. You can configure update behavior for the Agent and viam-server using the Viam app.

To use a specific version of viam-agent and viam-server, you can pin the version.

Important

When viam-agent updates 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 troubleshoot viam-agent.

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 agent subsystems, and any errors or warnings encountered during operation.

Next Steps

To see how to provision machines using viam-agent, see: