Skip to content
Viam Visualization

Running locally

You run the visualizer on your machine, point your code at it, and watch geometries / frames / drawings render in your browser.

Getting started

Section titled “Getting started”

Prerequisites

Section titled “Prerequisites”

You need Go, Node.js 22+, and pnpm. The setup script below installs the missing pieces; install manually if you’d rather pin specific versions.

Install

Section titled “Install”

From the repo root:

make setup

This installs fnm, Node.js 22, pnpm, Go, nlopt, buf, the Go protobuf tooling, project dependencies, and generates protobufs. On macOS, installing nlopt requires Homebrew.

The script prints a shell-config snippet at the end. Add it to ~/.zshrc or ~/.bashrc and restart your terminal so the new tools are on your PATH.

Run the visualizer

Section titled “Run the visualizer”
make up

Open http://localhost:5173. The first invocation also builds the static assets and the draw server; subsequent runs reuse the cached build.

Draw something from Go

Section titled “Draw something from Go”

Add the client to your project:

go get github.com/viamrobotics/visualization/client/api

Then draw to the running visualizer:

package main

import (
    "log"

    "github.com/golang/geo/r3"
    "github.com/viamrobotics/visualization/client/api"
    "github.com/viamrobotics/visualization/draw"
    "go.viam.com/rdk/spatialmath"
)

func main() {
    box, err := spatialmath.NewBox(spatialmath.NewZeroPose(), r3.Vector{X: 200, Y: 200, Z: 200}, "box")
    if err != nil {
        log.Fatal(err)
    }

    if _, err := api.DrawGeometry(api.DrawGeometryOptions{
        ID:       "box",
        Geometry: box,
        Color:    draw.ColorFromName("coral"),
    }); err != nil {
        log.Fatal(err)
    }
}

Run it while make up is running. A coral box appears at the origin. Calling DrawGeometry again with the same ID updates the box in place; pass a different ID (or omit it) to add a new entity.

A longer end-to-end script that draws a box, a line, a ring of pose arrows, and reference frames is at docs/examples/basic/main.go:

go run ./docs/examples/basic/main.go

For the full set of Draw* functions, see the client/api reference.

Connecting to a Viam machine

Section titled “Connecting to a Viam machine”

The visualizer can connect to live Viam machines to render their frame system, arms, and cameras. Drop your machine credentials into .env.local at the repo root using this format:

VITE_CONFIGS='
{
  "fleet-rover-01": {
    "host": "fleet-rover-01-main.ve4ba7w5qr.viam.cloud",
    "partId": "myPartID",
    "apiKeyId": "myApiKeyId",
    "apiKeyValue": "MyApiKeyValue",
    "signalingAddress": "https://app.viam.com:443"
  }
}
'

After make up, open the machine config panel (bottom right) and pick your machine.

Running multiple instances

Section titled “Running multiple instances”

Useful when comparing two client/api callers side by side. Pass STATIC_PORT to the second make up:

# Terminal 1
make up

# Terminal 2
make up STATIC_PORT=5174

Both apps render the same draw stream, so you’ll see your client/api calls reflected in both browsers at localhost:5173 and localhost:5174.

Troubleshooting

Section titled “Troubleshooting”

make setup finished but make up says “command not found”

Section titled “make setup finished but make up says “command not found””

You need to apply the shell-config snippet that make setup printed at the end and restart your terminal. The new binaries live under ~/.local/share/fnm and similar paths that aren’t on PATH until your shell config sources them.

make up fails with “Package nlopt was not found in the pkg-config search path”

Section titled “make up fails with “Package nlopt was not found in the pkg-config search path””

The draw server builds against nlopt, which older setups did not install. Re-run make setup, or install nlopt and pkg-config with the commands in the manual setup steps.

Port 5173 or 3030 is already in use

Section titled “Port 5173 or 3030 is already in use”

make up binds two: :5173 for the app and :3030 for the draw server. Each has its own override:

make up STATIC_PORT=5180 DRAW_SERVICE_PORT=3031

pnpm proto fails with “buf: command not found”

Section titled “pnpm proto fails with “buf: command not found””

buf isn’t on your PATH. Re-run make setup, or install manually following buf’s instructions, then retry.

client/api calls succeed but nothing appears

Section titled “client/api calls succeed but nothing appears”

Confirm make up is still running and that you can hit http://localhost:5173 in a browser. If the page loads but nothing renders, check the browser console for connection errors — both the Go client and the browser talk to the draw server on :3030.