Configure a Smart Machine

Before you can program a smart machine, you must configure it.

A machine’s configuration tells the code running the machine what resources (hardware components and software services) it has access to, as well as any relevant parameters for those resources.

To start configuring, go to the Viam app, create a new machine and follow the steps on your new machine’s Setup tab.

The setup steps copy your machine’s credentials to your machine and store them at /etc/viam.json. The credentials look like this:

  "cloud": {
    "app_address": "",
    "id": "123456ab-a1b2-12a3-a123-1a2b345cdefg6",

When you turn on your machine, viam-server starts up and, by default, it uses the credentials in its local /etc/viam.json to fetch its full config 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. All communication happens securely over HTTPS using secret tokens that are in a machine’s configuration.

After you have completed the setup steps and successfully connected to your machine, go to the Config tab to start adding to the configuration.

The Config tab

The Config tab on the Viam app is the place to configure everything about your machine.

You can use the mode selector to switch between Builder and Raw JSON:

  • Builder mode provides a graphical interface for configuring your machine resources.
  • Raw JSON mode provides a text editing field where you can write and edit the config manually.

The CONFIG tab of the Viam app with a box highlighting the CONFIG tab and the Mode selector (where you can select Builder or Raw JSON).

Regardless of the mode you choose, Viam stores the configuration file in JSON (JavaScript Object Notation).

If you add components in Builder mode and click Save Config at the bottom of the screen, you can switch to Raw JSON and see the JSON that has been generated by the builder.

An example config file for a machine with a board component, motor component, camera component, and vision service configured

The Config tab has subtabs for each section of your machine’s config:

  • Components: Components are the hardware of your machine.
  • Services: Services are the software that runs on your machine.
  • Modules: Modules provide modular resources, which are a way to add resource types or models that are not built into Viam.
  • Remotes: Remotes are a way to connect two separate machines so one can access the resources of the other.
  • Processes: Processes automatically run specified scripts when the machine boots.
  • Fragments: Fragments are a way of sharing and managing identical configuration files (or parts of config files) across multiple machines.
  • Auth/Network: The auth and network section allows you to configure machine-level API keys and set a bind address for viam-server.
  • Frames: Frames hold reference frame information for the relative position of components in space.


Components represent the pieces of hardware on your machine that you want to control with Viam.

You must configure each component with a type, a model, a name, attributes, and dependencies:

  • type: The broad component category, such as motor, arm or camera. Components of a given type have a common API.

  • model: Indicates the more specific category of hardware. Components of the same model are supported using the same low-level code.

  • name: Serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource. You can choose any unique name for a component.

  • attributes: A struct to define things like how the component is wired to the machine, its dimensions, and other specifications; attributes vary widely between models. See the component documentation for a given component type and model for more details.

  • depends_on: Any components that a given component relies upon, and that must be initialized on boot before this component is initialized. Many built-in components have convenient implicit dependencies, in which case depends_on can be left blank. For example, a gpio motor depends on the board to which it is wired, but it has a dedicated board attribute and viam-server will automatically initialize that board before it looks for the motor.

If you are configuring several similar components, you can use the Duplicate component button in the upper-right of a component’s configuration pane to create a new identical component beneath your existing one. Be sure to edit the duplicated component to change any parameters that are unique to the new component, such as its name and pins.

To delete a component, click the trash can icon in the upper-right of the component configuration pane.

For specific information on how to configure each supported component type, see the components documentation.


Services are built-in software packages that make it easier to add complex capabilities such as motion planning or object detection to your machine.

For services, the type specifies which of the Viam services you want to use on your machine, such as the vision service or the motion service.

The name serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource. You can choose any unique name for a service.

The other aspects of configuring a service are highly specific to the type of service. See the services documentation for more information.


Modular resources are a way to add resource types or models that are not built into Viam.

To add a modular resource as a component or service of your machine, configure a module per the modular resource documentation.


Configuring a remote is a way to connect two separate machines so one can access the resources of the other. Find more information in our remotes documentation.


To automatically run a specified command when the machine boots, configure a process. You can configure any command, for example one that executes a binary or a script, to run as a process.

Find more information in the processes documentation.


Webhooks allow you to trigger actions when certain types of data are sent from your machine to the cloud. For example, you can configure a webhook to send you a notification when your robot’s sensor collects a new reading.

Switch to Raw JSON mode to configure webhooks as follows:

  1. Paste the following JSON template into your raw JSON config. "webhooks" is a top-level section like "components", "services", or any of the other config sections.

      "webhooks": [
          "url": "<Insert your own cloud function or lambda URL for sending the event>",
          "event": {
            "attributes": {
              "data_types": ["binary", "tabular", "file"]
            "type": "part_data_ingested"
      "components": [
          "name": "local",
          "model": "rdk:builtin:pi",
          "type": "board",
          "namespace": "rdk",
          "attributes": {},
          "depends_on": []
          "name": "my_temp_sensor",
          "model": "rdk:builtin:bme280",
          "type": "sensor",
          "namespace": "rdk",
          "attributes": {},
          "depends_on": [],
          "service_configs": [
              "type": "data_manager",
              "attributes": {
                "capture_methods": [
                    "method": "Readings",
                    "additional_params": {},
                    "capture_frequency_hz": 0.017
      "webhooks": [
          "url": "",
          "event": {
            "attributes": {
              "data_types": ["binary", "tabular"]
            "type": "part_data_ingested"
  2. Replace the URL value with the URL of your cloud/lambda function.

  3. Edit the data_types list to include only the types of data you want to trigger on.

  4. Configure data capture and cloud sync for the relevant components. For example, if you want to trigger a webhook on temperature readings, configure data capture and sync on your temperature sensor. Be aware that the component must return the type of data you configured in data_types.

  5. Write your cloud/lambda function to process the request from viam-server. The following example function sends a Slack message with a machine’s details, such as robot and location IDs, when it receives a request:

    import functions_framework
    import requests
    import time
    def hello_http(request):
      payload = {
        "Org-ID": request.headers['org-id'] if 'org-id' in request.headers else 'no value',
        "Location-ID": request.headers['location-id'] if 'location-id' in request.headers else 'no value',
        "Part-ID": request.headers['part-id'] if 'part-id' in request.headers else 'no value',
        "Robot-ID": request.headers['robot-id'] if 'robot-id' in request.headers else 'no value'
      slack_url = "<paste in your own Slack URL"
      headers = {}
      response =, json=payload, headers=headers)
      request_json = request.get_json(silent=True)
      request_args = request.args
      return 'Sent request to {}'.format(slack_url)


Fragments are a way of sharing and managing identical resource configuration files across multiple machines. For example, if you have multiple machines with the same hardware, wired the same way, you can create and share a fragment and add it to any number of machines. When changes are made to the fragment, those changes are automatically carried to all machines that include the fragment in their config.

See Configure a Fleet for instructions on how to use fragments.


The auth section allows you to configure machine-level API keys for connecting over LAN.

The network section allows you to set the address viam-server binds to for accepting connections. By default, viam-server binds to when managed by the Viam app or when authentication and TLS are enabled.

Frame system

The frame system holds reference frame information for the relative position of components in space.

Configure a frame for a given component on its panel on the Components tab, then switch to the Frame System tab to visualize the relative positions. Find more information in the frame system documentation.


If you run into issues, here are some things to try:

  • Check the Logs tab to view log messages and errors from viam-server. You can also access the local log file on your machine if needed.
  • Make sure all configured components are actually saved to your config. If they aren’t, you will see an Unsaved Changes note next to the Save Config button at the bottom of the config screen.
  • Try restarting viam-server by clicking Restart in the upper right corner of the app. It takes a few minutes for the server to shut down and restart.
  • Make sure the issue is not hardware related. Some things to check are that the machine has adequate power, all wires are properly connected, and no chips or other hardware components are shorted or overheated.
  • See Troubleshooting for additional troubleshooting steps.
  • You can also ask questions in the Community Discord and we will be happy to help.

Local setup

Configuring viam-server with the Viam app allows you to make use of the cloud features of Viam:

However, if you are configuring a machine that can never connect to the internet, you can create a local configuration file on your machine. A locally-configured machine will not be able to access Viam’s cloud features.

Next steps

After configuring your machine, you can use the Viam SDKs to program and control your machine.

If you want to try configuring a machine but don’t have any hardware on hand, try the Build a Mock Robot tutorial.

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.