Install viam-server on Linux Systems

The viam-server is distributed as an AppImage. The AppImage is a single, self-contained binary that should run on any Linux system with the correct CPU architecture, with no need to install any dependencies (excepting FUSE as detailed in the troubleshooting section at the end). MacOS users need to follow the installing viam-server on macOS guide. Windows and 32-bit systems are not supported.

Installation Instructions

In short, you’ll download the file, make it executable, and run its self-install option to set it up as a system service. If you don’t want to run it as a service, just run it. It’s simply an executable binary.

URLs

Detailed Steps

Determine the CPU architecture (x86_64 or aarch64) of the target device by running uname -m on the command line. (Raspberry Pi and Jetson boards are aarch64 and most desktops and laptops are x86_64.)

Choose which URL to download from the list above. Run the following command (with the correct URL) to both download it and rename it to “viam-server” for ease of use:

curl -o viam-server http://packages.viam.com/apps/viam-server/viam-server-latest-aarch64.AppImage

Make the file executable by running:

chmod 755 viam-server

To run viam-server, you have two options:

Running Directly from the Command Line

To run viam-server directly from the command line, you can use the following command, replacing “myconfig” with the name of your configuration file. sudo is necessary on a Pi to access GPIO pins, and it may be necessary in other cases depending on hardware permissions.

sudo ./viam-server -config myconfig.json

To connect this instance of viam-server with a Viam app robot, the contents of myconfig.json should be pasted from the COPY VIAM-SERVER CONFIG button at the top right of the SETUP tab of your robot on https://app.viam.com.

Screenshot of the top of the SETUP tab showing the COPY VIAM-SERVER CONFIG button in the upper right, highlighted with a red box.

Installing as a System Service

This is more common when setting up viam-server on a Raspberry Pi or something that will essentially only be turned on when you want to use the robot, so you want viam-server to start every time on boot.

The following command will create a systemd service file at /etc/systemd/system/viam-server.service and set it to start on boot, using a config placed at /etc/viam.json. It will also move the actual binary (AppImage) to /usr/local/bin/viam-server (regardless of the previous filename.) Run the following command:

sudo ./viam-server --aix-install

To connect this viam-server with a Viam app robot, navigate to your robot page on https://app.viam.com. At the top right of the SETUP tab, click COPY VIAM-SERVER CONFIG and paste it into /etc/viam.json.

Start the service by running:

sudo systemctl start viam-server

The service is an AppImage and will check for updates and self-update automatically each time the service is started. Self-updates can take a couple of minutes, so the service may sometimes take a moment to start while this runs. You can disable this by commenting out the ExecPre line (the one with –aix-update on it) in the service file.

Next Steps

Continue to our Managing viam-server Guide to learn about running viam-server.