Installation Guide

To use Viam software with your robot, you need to install and run a binary called viam-server on the computer you want to use to control the robot. See What is Viam? for more information.

Preparation

Make sure your system is compatible with Viam. You can run viam-server on any device that runs:

  • any Linux 64-bit operating system (except FUSE)
  • macOS
Desktop computer

If you plan to run viam-server on your laptop or desktop with a Linux or Mac operating system, no special prep is required. Proceed to Install viam-server.


If you are using a single board computer (SBC) or a microcontroller, prepare your device by following the relevant setup document:

Raspberry Pi

Raspberry Pi Setup

BeagleBone A I-64

BeagleBone Setup

S K - T D A 4 V M

SK-TDA4VM Setup

Jetson Nano

Jetson Nano Setup

Jetson A G X Orin Developer Kit

Jetson AGX Orin Setup

E S P 32 - espressif

Microcontroller Setup

Install viam-server

Please accept marketing cookies to watch this YouTube video.

Once you have a compatible operating system on your computer, you are ready to install viam-server.

  1. Go to the Viam app and add a new robot. If this is your first time using the Viam app, you first need to create an account.
  2. Click the Setup tab on your robot page.
  3. Select the Mode and Architecture settings for your device.
  4. Follow the steps on the Setup tab to install viam-server. Also detailed in Detailed Installation Instructions.

Detailed Installation Instructions

viam-server is distributed as an AppImage. The AppImage is a single, self-contained binary that runs on any 64-bit Linux system (except FUSE), with no need to install any dependencies.

  1. Download the Viam app config to your computer. viam-server uses this config file to connect to app.viam.com. This connection allows the robot to pull its full configuration information and allows you to monitor and control your robot from the Viam app. Download your robot’s config file from the Setup tab of your robot on the Viam app.
  1. Download and install viam-server.

    Run viam-server locally on your Mac with the config you just downloaded. Replace <YOUR_ROBOT_NAME> with the name of your robot from the Viam app.

    To determine the CPU architecture (x86_64 or aarch64) of your device, run uname -m on the command line. Raspberry Pi and Jetson boards are aarch64 and most desktops and laptops are x86_64.

    Stable:

    curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-aarch64.AppImage -o viam-server &&
  chmod 755 viam-server && sudo ./viam-server --aix-install

    Latest:

    curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-latest-aarch64.AppImage -o viam-server &&
  chmod 755 viam-server && sudo ./viam-server --aix-install

    Stable:

    curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-x86_64.AppImage -o viam-server &&
  chmod 755 viam-server && sudo ./viam-server --aix-install

    Latest:

    curl https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-latest-x86_64.AppImage -o viam-server &&
  chmod 755 viam-server && sudo ./viam-server --aix-install

    If you do not want to run viam-server as a service, you can also run it manually as a binary.

  1. Connect and configure. Go to the Setup page on the Viam app and wait for confirmation that your robot has successfully connected.

viam-server is available for macOS users through Homebrew.

  1. Install viam-server on your Mac

    brew tap viamrobotics/brews && brew install viam-server

  2. Download the Viam app config to your Mac. viam-server uses this config file to connect to app.viam.com. This connection allows the robot to pull its full configuration information and allows you to monitor and control your robot from the Viam app. Download your robot’s config file from the Setup tab of your robot on the Viam app.

  3. Start viam-server on your Mac. Run viam-server locally on your Mac with the config you just downloaded. Replace <YOUR_ROBOT_NAME> with the name of your robot from the Viam app.

    viam-server -config ~/Downloads/viam-<YOUR_ROBOT_NAME>-main.json

  4. Connect and configure. Go to the Setup page on the Viam app and wait for confirmation that your robot has successfully connected.

Starting viam-server on Linux

To run viam-server, you have two options:

Start manually 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 some devices to access hardware.

sudo ./viam-server -config myconfig.json

Start automatically on boot

If you install viam-server as a system service, viam-server starts automatically every time you boot your device. Note that this is the default way viam-server is set up if you follow the Setup tab instructions on the Viam app.

For this setup your configuration file must be at /etc/viam.json.

The following command creates a systemd service file at /etc/systemd/system/viam-server.service and sets 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).

sudo ./viam-server --aix-install

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

Manage viam-server

Manage viam-server

Control and troubleshoot viam-server.

Update viam-server

Update viam-server

Update your version of viam-server.