Manage viam-server

Run as a system service

After installation, the viam-server AppImage binary will be located at /usr/local/bin/viam-server, and a systemd service file will be placed at /etc/systemd/system/viam-server.service. By default, viam-server is configured to start when the machine boots.

Running viam-server as a system service is the recommended method for Linux.

You can use the following commands to manage viam-server when installed as a system service. These commands require that you store your configuration file at /etc/viam.json.

Start

sudo systemctl start viam-server

Stop

sudo systemctl stop viam-server

Restart

sudo systemctl restart viam-server

Enable (start automatically with system boot, default)

sudo systemctl enable viam-server

Disable (do not start automatically with system boot)

sudo systemctl disable viam-server

Run from the command line

When running viam-server on the command line, you can use the following commands to manage the process. If viam-server is already running as a system service, be sure to stop the service first before using these commands.

Start

Run the following on the command line to start viam-server, providing the path to your configuration file:

sudo viam-server -config /path/to/my/config.json

If you followed the Installation Guide, your machine’s configuration file is available at /etc/viam.json. You can provide this path in the above command, or move the configuration file to a desired location and change the path in this command accordingly.

Note that on a Raspberry Pi, viam-server must always run as root (using sudo) in order to access the DMA subsystem for GPIO. When running viam-server from your home directory on a Linux computer, you do not need to use sudo.

Stop

Press Ctrl + C on your keyboard within the terminal session where you are running viam-server to stop it.

By default, viam-agent automatically upgrades to the latest stable version of viam-server. You can change this behavior in the version_control settings of your machine in the Viam app. For example, the following version_control configuration will always update to the latest stable release of viam-agent and the latest development release of viam-server:

{
  "agent": {
    "version_control": {
      "agent": "stable",
      "viam-server": "dev"
    }
  },
  "components": [ ... ]
}

To use the new versions of viam-server and viam-agent, restart viam-agent. When you stop or restart viam-agent, the agent also restarts viam-server.

To disable automatic updates, configure the version_control settings of your machine in the Viam app to a specific version number. For example, the following version_control configuration pins viam-server to version 0.52.1, preventing viam-server from updating to a more recent version:

{
  "agent": {
    "version_control": {
      "agent": "stable",
      "viam-server": "0.52.1"
    }
  },
  "components": [ ... ]
}

If you are changing to a different version of viam-server and viam-agent, restart viam-agent. When you stop or restart viam-agent, the agent also restarts viam-server.

As a system service

If you are running viam-server as a system service, run the following command to view log messages:

sudo journalctl --unit=viam-server

Use the arrow keys to page vertically or horizontally through the log messages.

You can also “tail” the logs, viewing new messages as they come in with:

sudo journalctl -f --unit=viam-server

Use the q key to stop following the logs.

You can also view log messages specific to viam-server in the syslog with the following command:

grep viam-server /var/log/syslog

From the command line

If you are running viam-server on the command line, log messages are written to standard out (stdout) in the same terminal session you started viam-server in.

You can also view log messages specific to viam-server in the syslog with the following command:

grep viam-server /var/log/syslog

Remove the system installed service with the following three commands:

sudo systemctl disable --now viam-server
sudo rm /etc/systemd/system/viam-server.service
sudo systemctl daemon-reload

To remove the configuration file, run:

sudo rm /etc/viam.json

To remove various Viam caches and logs for the root (service) user, run:

sudo rm -r /root/.viam/

If you ever run viam-server directly, to remove various Viam caches and logs for your own user run:

rm -r ~/.viam/

To remove the viam-server binary itself, run:

sudo rm /usr/local/bin/viam-server