Manage viam-server

Once you’ve installed viam-server, you can chose to run it as a system service or directly on the command line. Running as a system service enables you to configure viam-server to start automatically when your system boots, and is the default installation option on Linux. Running on the command line is suitable for local development.

Run viam-server

Select the tab for your platform:

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 own 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. If you don’t yet have a configuration file, you can build a new configuration file.

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.

Run from the command line

After installation, viam-server can be run directly on the command line.

Running viam-server on the command line is the recommended method for macOS.

You can use the following commands to manage viam-server on the command line:

Start

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

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

If you followed the Installation Guide, your machine’s configuration file is available in your ~/Downloads/ directory, named similarly to viam-machinename-main.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. If you don’t yet have a configuration file, you can use the example configuration file provided at /opt/homebrew/etc/viam.json or you can build a new configuration file.

Stop

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


Run as a system service

Installing viam-server as a system service is not recommended for most use cases on macOS. However, if you are looking to create a machine that runs on macOS and you want it to run viam-server automatically when your macOS system boots, then you will need to run viam-server as a service.

Once you have installed viam-server on your macOS computer, use the following commands to control the service. These commands require that you store your configuration file at /opt/homebrew/etc/viam.json.

Start

brew services start viam-server

Stop

brew services stop viam-server

Restart

brew services restart viam-server

Update viam-server

Select the tab for your platform:

viam-server is distributed for Linux as an AppImage, and includes a built-in self-update feature. When you run viam-server as a service on Linux, it will check for updates automatically on launch, and update itself if a newer version is detected.

The automatic update behavior of viam-server should meet the needs of most deployments, but if you need to manually force an update, you can do so with the --aix-update flag:

sudo viam-server --aix-update

Disable service-based updates

If you want to disable viam-server from automatically checking for updates each time you launch it, comment out the ExecStartPre line from your /etc/systemd/system/viam-server.service service file (by prepending with a # character), so that it matches the following:

# ExecStartPre=-/usr/local/bin/viam-server --aix-update

Then, reload the service file with the following command:

sudo systemctl daemon-reload

To resume automatic update checking, delete the leading # character once more, and run sudo systemctl daemon-reload again.

viam-server is distributed for macOS through the Homebrew package manager, which includes a built-in update feature.

To upgrade to the latest version of viam-server using Homebrew:

brew upgrade viam-server

Homebrew does not support automatic updates, so you will need to manually perform this step each time you wish to check for updates. We recommend running brew upgrade viam-server on a regular basis.

View viam-server logs

viam-server writes log messages as it starts up and runs, providing useful information when managing or troubleshooting the process. Use the following commands to view these log messages locally on your system.

Select the tab below for your platform:

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

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

You can also access the local viam-server log file using the following command:

cat $(brew --prefix)/var/log/viam.log

Uninstall viam-server

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

Uninstall viam-server with the following command:

brew uninstall viam-server

To remove various Viam caches and logs, run:

rm -r ~/.viam/

To remove the configuration file, run:

sudo rm /etc/viam.json

Troubleshooting

You can find additional assistance in the Troubleshooting section.