Configure a managed process

To run a program or control code when your machine is online, configure a process. The process is managed by viam-server. You can configure processes to run once upon startup or indefinitely.

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.

In the process configuration panel, configure the attributes for your process:

AttributeTypeRequired?Description
Executable (name)stringRequiredThe command you want to execute when your machine connects to the server. On many operating systems, you can find the executable path of commands by running which <command-name>.
Arguments (args)string[]OptionalArguments to follow the command.
Working directory (cwd)stringOptionalWhere you want the process to execute. Defaults to the directory where viam-server executes.
username (not available in builder mode)stringOptionalRun this process as a different user. Example: "username": "ubuntu".
env (not available in builder mode)Map<string, string>OptionalEnvironment variables for the process. Environment variables are encrypted in transit but are stored in plain text in the configuration file that resides on the machine. Example: "environment": { "SVC_API_KEY":"VALUE" }.
Logging (log)booleanOptionalToggle logging of errors and other messages on or off.
Default: false.
Execute once (one_shot)booleanOptionalToggle 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 machine appears offline in the Viam app. This machine should only be used for quick processes.
  • If false, the process continues to run and is restarted if the process terminates in any way. The process does not block viam-server.
Default: false.

Click Save in the upper right corner of the screen.

Example

The following example executes the command python3 my_cool_script.py in your /home/myName/project/ directory every time a machine boots, and restarts the process if it stops running.

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.

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

Set up dependencies

If you are configuring a process that requires dependencies, such as the Viam SDKs, you must install those dependencies so viam-server has access to them.

For Python scripts, we recommend you install dependencies into the folder that contains the code you want to execute:

sudo apt install -y python3-pip
pip3 install --target=machine viam-sdk <other-required-dependencies>

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.