Installation Guide

To use Viam software with your machine, install and run the viam-server binary on the single board computer (SBC) or other computer that will run your machine and is connected to your hardware. Installing on a laptop or desktop computer is useful if you don’t have an SBC available, or if you want to run a Viam service with your machine that requires more computing resources than are otherwise available on an SBC.

For an overview of the Viam software platform, see Viam in 3 minutes.

Prepare your board

If you are using one of the following boards, click on the card to follow the guide for that board:


Viam also provides a lightweight version of viam-server which can run on resource-limited embedded systems that cannot run the fully-featured Robot Development Kit (RDK). If you are using a microcontroller, prepare your board using the following guide:


Other SBCs such as the RockPi S and Orange Pi Zero 2 can run Viam with an experimental periph.io based modular component.

Install viam-server

If you have a compatible operating system, follow along with the steps outlined below or with the video beneath it to install viam-server:

viam-server is distributed for Linux as an AppImage. The AppImage is a single, self-contained binary that runs on 64-bit Linux systems running the aarch64 or x86_64 architectures, with no need to install any dependencies (except for FUSE, which is required by the AppImage format).

To install viam-server on a Linux computer:

  1. Determine if FUSE version 2 is installed on your Linux system:

    find /usr -name libfuse.so.2
    

    If the above command does not return a path to the libfuse.so.2 file, install FUSE version 2 according to your Linux platform:

    • If installing viam-server on a Raspberry Pi running Raspberry Pi OS (Debian GNU/Linux 12 bookworm or later), install FUSE version 2 with the following command:

      sudo apt install libfuse2
      
    • If installing viam-server on Ubuntu, install FUSE version 2 with the following commands:

      sudo add-apt-repository universe
      sudo apt install libfuse2
      
    • If installing viam-server on other Linux distributions, or for more information, see FUSE troubleshooting.

    Do not install the fuse package (that is, without a version number). viam-server requires FUSE version 2 specifically (libfuse2).

  2. Go to the Viam app and add a new machine by providing a name in the New machine field and clicking Add machine. If this is your first time using the Viam app, you must create an account first.

    The ‘First Location’ page on the Viam app with a new machine name in the New machine field and the Add machine button next to the field highlighted.

  3. On the Setup tab, select Linux (Aarch64) or Linux (x86_64) for the appropriate Architecture for your computer. On most Linux operating systems, you can run uname -m to confirm your computer’s architecture.

  4. Follow the steps shown on the Setup tab to install viam-server on your Linux computer.

  5. Once you have followed the steps on the Setup tab, viam-server is installed and running. Return to the Setup page on the Viam app and wait for confirmation that your computer has successfully connected.

By default, viam-server will start automatically when your system boots, but you can change this behavior if desired.

viam-server is available for macOS users through Homebrew, and supports both Intel and Apple Silicon macOS computers. To install viam-server on a macOS computer:

  1. If not installed already, install Homebrew.

  2. Go to the Viam app and add a new machine by providing a name in the New machine field and clicking Add machine. If this is your first time using the Viam app, you must create an account first.

    The ‘First Location’ page on the Viam app with a new machine name in the New machine field and the Add machine button next to the field highlighted.

  3. On the Setup tab, select Mac as the Architecture.

  4. Follow the steps shown on the Setup tab to install viam-server on your macOS computer.

  5. Once you have followed the steps on the Setup tab, viam-server is installed and running. Return to the Setup page on the Viam app and wait for confirmation that your computer has successfully connected.

Manage viam-server

To learn how to run, update, or uninstall viam-server, see Manage viam-server.

Next steps