Deploy software to machines

Deploy modules (hardware drivers, control logic, or other custom code) to one machine or an entire fleet. You configure the module in a fragment, apply the fragment to your machines, and the machines download the module from the Viam registry automatically.

Prerequisites

  • A module uploaded to the Viam registry. See deploy a module for how to upload.
  • A fragment for your fleet configuration. If you don’t have one yet, create one first.

1. Add the module to a fragment

  1. Navigate to your fragment’s page at app.viam.com/fragments.
  2. Click + and select Configuration block.
  3. Search for your module in the registry and add it.
  4. Configure the module’s attributes as needed.
  5. Click Save.

2. Set the version strategy

Each module in the fragment has a version field. On the fragment card for the module, find the Update version section:

  • Latest version: the machine downloads the newest version when it syncs. This is the default.
  • Pin to version: the machine stays on a specific version and does not update automatically.
  • Pin to tag: the machine uses whichever version the fragment tag points to. This option appears only when the fragment has tags. See reuse configuration for how to create tags.

To control when updates are applied, configure a maintenance window. See manage versions for details.

3. Apply the fragment to machines

Through the Viam app:

  1. Navigate to each machine’s CONFIGURE tab.
  2. Click + and select Configuration block.
  3. Search for your fragment and select it.
  4. Click Add fragment.
  5. Click Add fragment again to confirm, then Save.

Through provisioning:

Include the fragment ID in your viam-defaults.json file. New machines apply the fragment automatically on first boot. See provision devices.

Through the CLI:

viam machines part fragments add --part=<part-id> --fragment=<fragment-id>

To find your part ID, run viam machines part list --machine=<machine-id>. To find the fragment ID, copy it from the fragment’s page in the Viam app or run viam organizations list and check your fragments.

4. Verify the deployment

  1. Navigate to a machine’s CONFIGURE tab and confirm the module appears in the resource list.
  2. Go to the CONTROL tab and test the deployed components or services.
  3. Check the LOGS tab for any errors from the module.

On the fleet dashboard at app.viam.com/fleet/machines, confirm your machines are online and showing the expected viam-server version.

Related pages