Manage Locations and Sub-locations

In Viam, every machine belongs to a location. A location is a virtual grouping of machines that allows you to organize machines and manage access. Generally, a location defines a group of machines that are geographically close to each other. If you are familiar with Google Drive, you can think of a location as similar to a folder within a shared drive.

For example, an organization called Good Robots Inc has two warehouses across New York and Oregon. Good Robots Inc can organize its machines into two locations based on their physical presence in a warehouse.

You can also use locations as proxies for environments such as “Production” and “Testing” or other groupings. Locations do not have to correspond with physical locations.

Each machine you add to Viam belongs to a location. Each location belongs to an organization.

Add a location

When you create a new organization, Viam automatically creates a new location for you. You can create additional locations by typing a new location name in the New Location field in the left side navigation bar on the FLEET page and clicking Add.

Click a location’s name to display the list of machines associated with that location.

Create a sub-location

To create a sub-location you must first create the sub-location as a location and then choose a parent location:

1. Create a location and add at least one machine to it.
2. At the bottom of the location’s page, use the New Parent Location dropdown to choose a parent location.
3. Click Change.

You can nest locations up to three levels deep.

To move a sub-location to the top level of locations, select Root from the New Parent Location dropdown and then click Change.

Share a location

A location always belongs to the organization it was created in. Members of the organization have access to all locations in the organization by default.

For more information on the permissions the roles assign for each resource, see Permissions.

You can share a location beyond its organization by sharing a location with an additional organization:

Share a location with an additional organization

Share your location with another organization you belong to by selecting the organization from the Add Organization dropdown menu and clicking Share.

To share your location with an organization you are not a member of, enter the organization ID (a string like 1ab2c3d1-1234-123a-abcd-abcdef123456) and click Share. Members of the other org can find the org ID on their org settings page.

The location’s page lists the newly added organization, along with the organization identified as the primary owner:

The list of organizations includes the names of organizations to which you belong, and the org IDs of organizations to which you do not belong.

Remove an organization from a shared location

You can remove any organization except the primary owner from the shared list by clicking the X to the right of the location in the shared list.

Rotate a secret key

If you ever need to rotate this key, click on the Generate Key button to generate a new key.

Viam supports flexible key rotation with up to two keys in use at one time. After generating a new secret key, update all references to the key in your code as soon as possible and then remove the old key.

Share a location with Viam support

If you request support, you must share your location with the Viam Support team. To do so, navigate to the location you need support with and click, Add Viam support.

Once you have received support, you can remove Viam Support from your location by clicking Remove Viam support.

Delete a location

You can delete a location that is empty of machines by clicking the trash can icon next to the location name at the top of the page for that location. The icon will not appear if there are any machines in the location.