Configure a Process to Run on Your Machine

To automatically run a specified command when your machine boots, configure a process. A process can be any command, for example one that executes a binary or a script. You can configure a process to run once when the machine first starts, or to run continuously alongside viam-server.

Set up dependencies for Viam SDK code run as a process

If you are configuring a process to run a script that does not use Viam SDKs, skip this section and continue to Configure a process. Due to the way processes are designed for stability, if you are configuring a process to run a Viam SDK script, you need to install the relevant SDK as well as other required dependencies in a specific way on your SBC:

  1. ssh into your board and install pip:

    sudo apt install python3-pip

  2. Create a folder inside your home directory to hold your code. These example steps use the folder name robot:

    mkdir robot

  3. Then install the Viam Python SDK (and other dependencies if required) into that folder:

    pip3 install --target=robot viam-sdk <other-required-dependencies>

  4. Add your code to your new folder:

    scp main.py user@host.local:/home/myboard/robot/main.py

Configure a process

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Process. Your process is automatically created with a name (id in JSON) like process-1 and a card matching that name on the CONFIGURE tab. Navigate to that card.

Then fill in the following fields:

Attribute (Builder Mode)Attribute (JSON)TypeInclusionDescription
ExecutablenamestringRequiredThe command you want to execute when your machine connects to the server.
ArgumentsargsstringOptionalArguments to follow the command.
Working directorycwdstringOptionalWhere you want the process to execute. Defaults to the directory where viam-server executes.
LogginglogbooleanOptionalToggle logging of errors and other messages on or off. Default: false.
Execute onceone_shotbooleanOptionalToggle whether to execute the command just once or keep running the process indefinitely.
  • If true, the process executes once at viam-server startup. Until the process completes, viam-server startup is blocked and the robot appears offline in the Viam app, so this should only be used for quick processes.
  • If false, the process continues to run. If the process crashes, it automatically restarts. It does not block viam-server. Default: false.

Click Save in the upper right corner of the screen to save your config.

Example

The following example configuration executes the command python3 my_cool_script.py in your /home/myName/project/ directory every time your machine boots, and keeps it executing indefinitely.

The CONFIGURE tab with a process called run-my-code configured. The executable is python3, the argument is my_cool_script.py, and the working directory is /home/myName/project. Logging is turned on and execute once is turned off.

The corresponding JSON looks like this:

"processes": [
    {
      "id": "run-my-code",
      "log": true,
      "name": "python3",
      "args": [
        "my_cool_script.py"
      ],
      "cwd": "/home/myName/project/"
    }
  ]

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.