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 crashes or is killed. 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>