Configure multiple similar machines

Viam has a built-in tool called fragments for using the same configuration on multiple machines. A fragment can configure just one resource a machine uses, or all the resources it uses. If most of your machines are similar but not identical, you can use fragments and then manually add modifications for individual machines.

When you update a fragment, it updates the configurations of all machines that use that fragment.

For information on provisioning many machines, see Provisioning.

Create a fragment

1. Configure one machine

Start by configuring one of your machines.

In the Viam app, use the CONFIGURE tab to build a configuration for all components and services you want to use on all your machines.

Configuration builder UI

2. Copy the raw JSON

In your machine’s CONFIGURE tab, switch to JSON and copy the raw JSON.

JSON subtab of the CONFIGURE tab

3. Create a fragment

On the FLEET page, go to the FRAGMENTS tab.

Click Create fragment, and paste the copied JSON configuration into it.

Set your privacy settings. There are three options for this:

  • Public: Any user inside or outside of your organization will be able to view and use this fragment.
  • Private: No user outside of your organization will be able to view or use this fragment.
  • Unlisted: Any user inside or outside of your organization, with a direct link, will be able to view and use this fragment.

Click Save.

If you want to edit the fragment later, do it from this screen.

app.viam.com/fragment interface
Delete

4. Delete the original configuration (optional)

Now that the configuration is saved as a fragment, you can delete each resource in the original config from your machine and replace the config with the fragment in the next step. In this way, you can keep all your machines up to date whenever you change the fragment.

Add a fragment to multiple machines

With your fragment created, you can add it to as many machines as you’d like. You can do this manually, as described here, or using provisioning.

Add fragment

1. Add the fragment to one machine

On your machine’s CONFIGURE tab, click the + button and select Insert fragment. Search for your fragment and add it.

Click Save in the upper right corner of the screen.

Repeat

2. Repeat for each machine

Repeat step 1 for each of the machines that you want to configure in the same way.

If some of your machines have slight differences, you can still add the fragment and then add fragment overwrites in the next section.

Modify a fragment

If your machines are similar but not identical, you can use a fragment with all of them, and then overwrite parts of it to customize select fields of the configuration without modifying the upstream fragment.

1. Edit your machine’s config

Go to the CONFIGURE tab of the machine whose config you want to modify, and make your edits just as you would edit a non-fragment resource.

You can click the {} button to switch to advanced view and see the changes.

Don’t forget to Save.

2. Check your machine’s logs

After configuring fragment overwrites, check your machine’s LOGS tab. If there are problems with overwrites to the fragment, the overwrites will not be partially applied and the configuration changes will not take effect until the configuration is fixed.

Reset to fragment

3. (Optional) Revert fragment modifications

If you need to restore the original fragment, click the … in the upper right corner of the card you modified, and click Revert changes. Now, the fragment will be identical to the upstream fragment.

Next steps

To set up a larger fleet without manually adding a fragment to each machine configuration, you can use Viam’s provisioning manager, Viam Agent:

Provisioning Machines

Flexibly provision new machines using viam-agent.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.