Get started

Connect a machine to the Viam platform so you can configure, control, and monitor it from anywhere. You’ll create a machine in the Viam app, install Viam on your machine, and confirm it’s online.

1. Create a machine in the Viam app

  1. Go to app.viam.com and log in (or create an account).
  2. Create or select an organization, then create or select a location.
  3. Click Add machine.
  4. Give your machine a name (e.g., my-first-machine). Click Add machine.

The app creates a machine entry and opens the CONFIGURE tab. A banner prompts you to set up the machine part.

2. Open the setup page

  1. Click View setup instructions in the banner.
  2. In the wizard dialog that opens, click Go to Advanced setup.

3. Select your platform

Use the Platform you want to run on dropdown to select the operating system and architecture of the compute machine for your robot — the computer to which you’ve attached cameras, sensors, arms, or other components.

Options include Linux / Aarch64, Linux / x86, Mac, Windows native, Windows (WSL), Linux / Armv7l, and ESP32.

4. Select your installation method

If your platform supports multiple installation methods, a second dropdown appears.

  • viam-agent: Choose this unless you have a reason not to.
  • manual: Installs viam-server directly.

5. Run the install command

The setup page displays platform-specific install instructions. Follow the steps shown on your compute machine.

6. Wait for confirmation

After the install command finishes, the setup page polls for your machine’s connection status. When the banner changes to “Your machine is connected!”, your machine is online and ready to configure.

This should happen within 30 seconds.

Troubleshooting

Machine shows offline in the Viam app
  • Is viam-agent running? On Linux, check with sudo systemctl status viam-agent. If it’s not running, start it with sudo systemctl start viam-agent. This will also start viam-server.
  • Does the machine have network access? Verify with ping google.com.
  • Is the config correct? Inspect /etc/viam.json and confirm it contains valid credentials. If in doubt, re-run the install command from the Viam app.
"Permission denied" during install
  • The install script requires sudo. Run the curl command exactly as shown on the setup page.
  • On some systems, your user may not be in the sudo group. Consult your device’s documentation for how to grant sudo access.
viam-server starts but immediately exits
  • Check the logs: sudo journalctl -u viam-server -n 50.
  • Common causes: invalid JSON in /etc/viam.json, port conflicts (another service on port 8080), or missing system libraries.

7. Connect with code

Your machine is online. Now connect to it programmatically.

  1. Go to your machine’s page in the Viam app.
  2. Click the CONNECT tab.
  3. Select SDK code sample in the sidebar.
  4. Choose your language (Python, TypeScript, Golang, C++, or Flutter).
  5. Toggle Include API key to populate the code sample with your machine’s credentials.
  6. Copy the code sample, install the SDK, and run it.

If the connection succeeds, the script prints your machine’s available resources.

What’s next

  • Configure hardware — Add cameras, motors, sensors, and other components to your machine.