Manage Locations and Sub-locations
In Viam, every robot belongs to a location. A location is a virtual grouping of robots that allows you to organize robots and manage access. Generally, a location defines a group of robots 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 robots 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 robot 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 robots 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:
- Create a location and add at least one robot to it.
- At the bottom of the location’s page, use the New Parent Location drop-down to choose a parent location.
- 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 drop-down 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.
There are two ways to share a location beyond its 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 drop-down menu and clicking Share.
The location’s page lists newly added organization, along with the organization identified as the primary owner:
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.
Share a location using location secret keys
Grant programmatic access to your location by sharing a location secret key.
You can see the secret keys for a location in the Location Secret Keys drop-down:
Copy the secret key by clicking on the clipboard icon. Use these keys in your SDK code and scripts to authenticate your access to the robots in your location in the cloud.
Caution
Be cautious when sharing location secret keys in your code or messages.
Do not make a secret key publicly available, as anyone who has the secret key can access your location, compromising the security of your system.
It is good practice to note where and when you share a location secret key.
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 robots 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 robots in the location.
Was this page helpful?
Glad to hear it! If there is anything we could be doing better, please create an issue.
We're sorry about that. If you'd like to talk to us for help, please join the Community Discord. To ensure we know what's wrong with this page, you can also open an issue.