Edit

Set up a computer or SBC

Get started by installing viam-server, the open-source software that drives your hardware and connects your device to the cloud.

Prerequisite: Make sure you have a supported operating system

Check if your system can run viam-server by running the following command in your terminal:

arch=$(uname -m); bits=$(getconf LONG_BIT); [[ ("$arch" == "x86_64" || "$arch" == "aarch64") && "$bits" == "64" ]] && echo "✅ Your system can run viam-server" || echo "❌ Your system cannot run viam-server"

viam-server can run on Linux 64-bit operating systems running on AArch64 (ARM64) or x86-64 architectures.

If you’re using Viam with a single-board computer (SBC) that does not yet have a 64-bit Linux operating system installed, start by flashing an OS. For convenience, we provide operating system installation instructions for some popular SBCs:

SBC setup instructions

If your SBC or other computer already has a supported operating system installed, you can skip this step.

bash -c '[[ "$(uname -s)" == "Darwin" && ("$(uname -m)" == "x86_64" || "$(uname -m)" == "arm64") ]] && echo "✅ Your system can run viam-server" || echo "❌ Your system cannot run viam-server"'

(Get-WmiObject -Class Win32_OperatingSystem).OSArchitecture -eq "64-bit" -and (wsl --status 2>$null) -ne $null ? "✅ Your system can run viam-server" : "❌ Your system needs WSL for viam-server"

Windows note

viam-server can run on Windows Subsystem for Linux (WSL), but WSL itself does not currently support exposing many types of Windows hardware to the embedded Linux kernel. This means that some hardware, such as a connected webcam, may not be available to viam-server with WSL, even though it is fully supported for native Linux systems.

Native: Use native if you are using a WSL version prior to WSL 2 or need native USB support
WSL: Use WSL if you are using Python modules or other Linux dependencies

For 32-bit microcontrollers, see Set up an ESP32.

Install `viam-server` and connect your machine to the cloud

Install viam-server on the computer or single-board computer (SBC) that is directly connected to your hardware (for example sensors, cameras, or motors).

Make sure your computer or SBC is powered on and connected to the internet.
Create a Viam app account. The Viam app is the online hub for configuring and managing devices and data.
Add a new machine using the button in the top right corner of the LOCATIONS tab in the app. A machine represents your device.
From your machine’s page in the Viam app, click View setup instructions and follow the steps for your operating system. The app provides commands to install viam-server and connect it to the cloud with your machine’s unique credentials.
A secure connection is automatically established between your machine and the Viam app. When you update your machine’s configuration, viam-server automatically gets the updates.
You are ready to configure supported hardware on your machine.

How the machine gets its configuration

The machine setup steps displayed in the Viam app copy your machine’s credentials to your machine. When you turn on your machine, viam-server starts up and uses the provided credentials to fetch its configuration from the Viam app. Once the machine has a configuration, it caches it locally and can use the config for up to 60 days. Since the configuration is cached locally, your machine does not need to stay connected to the Viam app after it has obtained its configuration file.

If it is online, the machine checks for new configurations every 15 seconds and changes its config automatically when a new config is available. All communication happens securely over HTTPS using secret tokens that are in the machine’s config.

Manage your installation

On Linux installs, by default viam-server or viam-agent and viam-server will start automatically when your system boots. On macOS installs, viam-server does not start automatically on boot. You can change this behavior if desired.

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

For manual installs of only viam-server, see Manage viam-server.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!