Manage Machines

A machine is an organizational concept, consisting of either one part, or multiple parts working closely together to complete tasks. The machine represents the configuration and entry point for one or more computers (and the components they control) coupled into one logical grouping of parts that work together to complete tasks. A machine usually reflects a physical device, from a camera collecting images, to a wheeled rover, or an articulated arm on a factory floor. A machine always has a main part that receives client requests, and any number of other parts.

Add a new machine

Add a new machine by providing a name in the New machine field and clicking Add machine.

The ‘First Location’ page on the Viam app with a new machine name in the New machine field and the Add Machine button next to the field highlighted.

Click the name of a machine to go to that machine’s page, where you’ll find a variety of tools for working with your machine.

The banner at the top of the machine page displays the machine’s location, name, and a dropdown list of all parts of that machine.

If you’ve connected your physical machine running viam-server to its instance in the Viam app, the banner also displays when the machine was last online, which version of viam-server it is running, the host name, the IP address or addresses, and its operating system.

The machine page with menu tabs

For each machine in your fleet, you start by setting up the machine on the Setup tab:


The Setup tab contains information for starting an instance of viam-server on your machine’s computer.

Once you select the correct Architecture for your system in the upper left of the tab, follow the instructions on the page to connect and set up your machine.


When a machine or a machine part that is managed with the Viam app first comes online, it requests its configuration from the Viam app. Once the machine has a configuration, it caches it locally and can use the configuration for up to 60 days. The machine checks for new configurations every 15 seconds and changes its configuration automatically when a new configuration is available.

After connecting your machine, go to the Config tab, and start adding components, services, and other resources.

For more information, see the configuration documentation.


The configuration of your machine and the code it runs are kept separate to make debugging easier. The History tab shows timestamped changes to your machine’s configuration.

If you want to revert changes that you made, you can load a previous configuration by clicking the Load config button next to the respective configuration.

You can also change your timestamp format to ISO or Local depending on your preference.


To make debugging issues with your machines easier, each machine automatically sends its logs to the cloud. You can access your logs from the Logs tab in the Viam app and filter your logs for specific keywords or log levels:

You can also change your timestamp format to ISO or Local depending on your preference.


Once you have configured components and services for your machine, you can visually test and remotely operate them from the Control tab in the Viam app. For example, if you have configured a base with wheels, you can control your machine’s movement with an arrow pad and fields to change base’s speed. If you have configured a camera component, a window in the Control tab displays the camera output.

If you use remote control in the Viam app UI, all communication to the machine uses WebRTC. For local communication between parts Viam uses gRPC or WebRTC.

You can also access the control interface using the Viam mobile app, which you can find on the App Store and on Google Play.

Code Sample

To start programming your machine, go to the Code sample tab which contains boilerplate code snippets you can copy and paste into your SDK code to connect to your machine.

For more information on the SDKs, see Program your Machine with Viam’s SDKs.

There is also a JSON stub you can copy if you wish to have your machine communicate with another machine as a remote.


Your machine and the Viam app communicate securely using WebRTC with unique secrets.

The Security tab allows you to access, generate, and delete the Machine part secret keys and the Machine part API keys of your machine.

The Security tab of a machine’s page noting the Machine part API keys dropdown menu, with the clipboard icon on the far right and the Generate Key button underneath the dropdown.

You can copy a secret by clicking on the clipboard icon.

Delete a machine

You can delete a machine by navigating to its page in the Viam app and selecting Sure? and Delete machine in the lower left corner of the page.

The delete machine button and the confirmation checkbox (Sure?) next to it.

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.