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

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:
Install viam-server
Once you have a compatible operating system on your computer, you are ready to install viam-server
.
- 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.
- Click the Setup tab on your robot page.
- Select the Mode and Architecture settings for your device.
- 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.
- 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.
- 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.
- 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.
Install
viam-server
on your Macbrew tap viamrobotics/brews && brew install viam-server
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.Start
viam-server
on your Mac. Runviam-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
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
The following command creates a systemd service file at
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
Was this page helpful?
Glad to hear it! If there is anything we could be doing better, please create an issue.
We're sorry about that. If you'd like to talk to us for help, please join the Community Discord. To ensure we know what's wrong with this page, you can also open an issue.