Scaling with Viam using fragment versions: Safer configuration management

Gain full control over machine configurations with structured versioning, safer rollouts, and easy rollbacks.

Natalia Jacobowitz

Product Manager

Introduction: Why fragment versions matter

Managing machine configurations at scale is complex. Without version control, updates can quickly become unmanageable, and reversing mistakes can be challenging.

That’s why we built fragment versions.

Fragment Versions Demo - YouTube
Fragment Versions Demo Viam

What are fragment versions?

If you’ve worked with fragments, you know they simplify configuration management by enabling modular, reusable setups across machines. But what happens when you need to iterate on a fragment, test changes, or roll back to a previous version?

That’s where fragment versions come in.

Fragment versions allow teams to track changes, maintain machine stability, and deploy updates with confidence. They also work seamlessly with nested fragments, making it easy to manage complex, layered configurations while maintaining version control across all dependencies. Instead of modifying a live fragment and risking unintended consequences, you can create new versions, test them in isolation via tags, and roll them out when ready.

Managing fragment versions with tags

To provide even greater control over updates, fragment versions support tagging. Tags allow you to reference specific fragment versions in your machine configurations and provide flexibility in managing updates.

How to create and apply tags:

• When managing a fragment version, you can create and assign a tag (e.g., stable, testing, beta).
• Tags can be applied to any version of a fragment to organize updates.
• If a tested fragment version is successful, you can move a tag (e.g., stable) to that version, ensuring all machines using that tag update automatically.
• If an issue arises, you can roll back by moving the tag to a previous, known-good version.

Once you've assigned tags to different versions of a fragment, the next step is deciding how machines reference them.

Choosing how to use fragment versions

When you add a fragment to a machine, you can choose how the machine updates to new versions:

• Latest version (default) – The machine always updates to the latest version of the fragment as soon as a new version becomes available.
• Specific version – The machine stays on a fixed version of the fragment and does not update automatically.
• Tag-based versioning – The machine always uses the version of the fragment associated with a selected tag, such as stable.

This flexibility ensures teams can balance stability and iteration based on their needs.

Why fragment versions matter and who benefits

Fragment versions provide structured version control, reducing risk and improving efficiency for a wide range of users:

• Companies managing fleets – Safe, gradual updates across machines with tracked version history and easy rollbacks.
• Developers iterating frequently – Enables fast prototyping while maintaining stability via A/B testing.
• Collaborators & open-source users – Allows controlled updates without affecting production environments.

To see how this works in practice, let's look at RoboHaul, a company using fragment versions to safely deploy updates across a fleet of robots.

Real-world example: Optimizing RoboHaul's fleet

RoboHaul, a logistics automation company, operates a fleet of 200 heavy-duty transport robots in warehouses across the country. Their lead engineer, Alex, needs a structured way to introduce updates without disrupting operations. He uses fragment versions and tags to manage updates:

1. All machines use the latest fragment – By default, all 200 robots are assigned to the latest version of the navigation fragment.
2. Preparing for a test – Alex wants to test new changes while keeping most machines stable.
3. Setting up version tags – He tags the current fragment version as stable and also assigns canary to the same version. Then, he configures 195 machines to use stable and 5 machines to use canary.
4. Creating a new version – Alex makes updates to the navigation fragment, creating a new version.
5. Testing with canary – Once he feels the new version is ready to test, he moves the canary tag to this updated fragment version. The 5 canary machines now receive the latest changes for testing.
6. Validation and full rollout – If the new version performs well, Alex moves the stable tag to the same version, updating the remaining 195 machines.
7. Rollback if needed – If issues arise at any stage, Alex can move canary or stable back to the previous version, instantly reverting affected machines to a working state.

This structured approach ensures smooth, low-risk updates, allowing RoboHaul to test and deploy changes with confidence.

Smarter updates, greater reliability

Fragment versions provide structured version control, helping teams manage updates efficiently, minimize risk, and keep their machine configurations organized. Whether rolling out improvements to a single machine or a global fleet, this feature ensures a smooth and controlled process.

Start using fragment versions today and take the guesswork out of managing configurations at scale.