Quick Start: Install + Connect with Docker

Install the Voyant API tools in a Docker container and connect to your Carbon 30 over the host network.

The Docker container approach is recommended when:

You are not on Ubuntu LTS releases 22.04, 24.04, or 26.04
You want a consistent, dependency-free environment

Note: The container is headless — it runs the command-line tools, not the graphical Voyant Visualizer. Run the visualizer natively on your host; use Docker for the CLI tools and for verifying sensor connectivity.

Prerequisites

Docker Engine — Docker installation guide

⚠️ Install Docker Engine, not Docker Desktop. Docker Desktop handles ethernet differently and will prevent connection to your Voyant device.

Set up the connection on your host, not in the container. The container shares the host network (it runs with --network host), so configure the static-IP connection to the sensor on your host first — follow the connection steps for your OS (Ubuntu or Windows). The container then reaches the sensor over that host connection.

Procedure

1. Clone the repository:

   git clone https://github.com/Voyant-Photonics/voyant-sdk.git

2. Build the container:

   cd voyant-sdk/
   docker build -t voyant-sdk-container -f docker/Dockerfile .

Note: You can force a rebuild with the latest release using --no-cache:

docker build --no-cache -t voyant-sdk-container -f docker/Dockerfile .

3. Run the container:

   docker run --rm -it --name voyant-sdk-container --network host -v $(pwd):/workspace voyant-sdk-container /bin/bash

If you get a permissions error, prefix with sudo.

Note 1: The container gives you full access to send commands to the LiDAR and receive data, but limits some standard terminal commands (e.g. ip addr). Type exit to return to your regular terminal; re-run the docker run command to reopen it. Packages installed with apt inside the container will not persist after exit.

Note 2: --network host shares the host’s network only on Linux. On Windows or macOS, Docker runs inside a VM rather than directly on the host, so --network host does not expose your LAN to the container and it will not reach the sensor — connect from a Linux host (Docker Engine) for live sensor data.

Verifying Installation

voyant_hello_world

Expected output:

Welcome to the Voyant Photonics, Inc. API!
You have successfully installed the voyant-api package with:
 - Proto version: 0.2.2 (Proto)
 - API version:   0.4.4 (API)

Verifying Connectivity

Networking (multicast and the host interface) is the part most likely to need setup, so confirm the container can actually receive sensor data by running the live client check against your sensor:

voyant_carbon_client_check

With no arguments the client uses the default connection settings; see the client check reference for the --bind-addr / --group-addr / --interface-addr options when you need to target a specific interface. If your networking is set up correctly, you’ll see frames arriving:

[INFO  voyant_carbon_client_check] ###############
    Received frame:
    ...
    Points count: 7971
    Rate: 10.0 Hz (10s avg)

If it hangs without receiving frames, revisit your host networking (and, on Windows/macOS, the --network host behavior noted above).

Viewing Header Files

Header files from voyant-api-dev are installed at /usr/include/voyant_api/.