OLO Appliance

The OLO Appliance is robot-side software. It connects to an OLO account using a device API key, participates in a ROS 2 environment, hosts browser-initiated script execution, and exposes the SDK gRPC control plane.

Installation choices

Cloud Sim environments provision their Appliance automatically. OLO hardware appliances arrive with robot-side software installed. For a self-hosted release on Linux or WSL with Ubuntu 22.04 or newer, the current public installer is:

$ curl -sSL https://raw.githubusercontent.com/OLO-Robotics/olo-appliance-release/main/install.sh | bash
$ cd ~/olo-appliance/olo-appliance-release/app
$ ./setup.sh --defaults --dist

The release setup expects ROS 2 and its robot-specific dependencies to be available. ROS communication is handled in-process via rclnodejs; LAN clients and code execution use ws://localhost:<port>/local-rosbridge. Cloud clients connect via the OLO server /rosbridge WebSocket and WebRTC data channels. The setup prompts for OLO account credentials during the guided setup. For production or automated deployment, prefer a provisioned device API key over storing user credentials.

Updating the Appliance

The dashboard marks an appliance Update required when a newer release is published for the same ROS distribution and CPU or NPU variant. Its tools are unavailable until it is updated. Updates are applied on the appliance’s host, not from the dashboard; Copy image copies the target image, and the card returns to normal once the appliance reports the current release.

If the appliance’s host runs the OLO Hardware Manager, the card shows Open Hardware Manager instead of manual steps. It opens the manager on the appliance’s local network (port 3001), where the update can be applied directly; it is only reachable from that network.

For a Docker Compose deployment:

  1. Pause running appliance scripts and robot operations before restarting it.

  2. Select Copy image on the appliance’s card. The copied image already matches your deployment’s ROS distribution and CPU/NPU variant.

  3. Change the appliance service’s image: entry to the copied image. Keep its device API key, environment, network configuration, device access, and persistent volumes unchanged.

  4. From the directory containing your Compose file, pull and recreate the appliance service. Replace olo-appliance below if your service has a different name:

    $ docker compose pull olo-appliance
$ docker compose up -d --no-deps olo-appliance
$ docker compose logs --tail=100 olo-appliance

  5. Check that the appliance reconnects in the dashboard and the warning clears. If it remains, check that the running container uses the selected image.

For a docker run deployment, pull the selected image and recreate the container using your original deployment command with the new image tag and the same configuration and volumes. Restarting an existing container alone does not switch it to a newly pulled image. For a managed hardware appliance or a non-container installation, ask its operator to apply the release using the deployment procedure for that installation.

Appliances report their release version from the release after 2.3.4 onward. Once such a release is published, an appliance that reports no version is older than it and is marked Update required; its card shows the standard Jazzy image, so pick the matching Humble or NPU tag if your appliance uses one.

If the card says Version not reported, the server could not identify its installed release. Older appliances are checked through their existing maintenance build information when connected. Check the deployment’s image tag before choosing an update; an unknown version does not itself mean the appliance is outdated.

Registration and identity

Register an Appliance from the Portal’s Add Appliance flow. Copy the generated device API key when it is shown and provide it to the runtime:

OLO_APL_DEVICE_API_KEY=apl_your-device-api-key
OLO_APL_APPLIANCE_NAME=My Appliance

OLO_APL_ROBOT_ID is optional; the Appliance can resolve and persist its robot identity after registration. Treat the device key as a secret. To rotate it, use Account & Security > Appliance Device Keys, update the runtime environment, and restart or recreate the Appliance process.

ROS 2 configuration

The Appliance uses an in-process ROS 2 transport (rclnodejs). Cloud clients connect via the OLO server /rosbridge WebSocket and WebRTC data channels. LAN clients and code execution use ws://localhost:<port>/local-rosbridge on the appliance HTTP port.

Set OLO_APL_ROS_DOMAIN_ID when the robot does not use the default domain, and ensure that the Appliance process has sourced the same ROS distribution and workspace as the robot drivers. See ROS 2 Concepts for OLO for domains and namespaces.

SDK

The SDK is always enabled in the Appliance configuration. To change its listener port:

OLO_APL_GRPC_PORT=50151  # listener port (50151 is the default)

The current runtime starts separate Core, Spatial, Kinematics, and Navigation executors behind one Envoy listener. The listener host defaults to 127.0.0.1 and the port defaults to 50151. Playground scripts receive that target automatically.

The SDK surface depends on the robot’s ROS graph. Core topic operations require matching topics and message types; Spatial requires TF data; Kinematics requires a usable MoveIt setup; Navigation requires a usable Nav2 setup. Vision in the SDK contains client-side camera geometry, depth, alignment, and tracking helpers; it is not the Portal’s video, recording, or AI-vision management API.

Platform management is separate

The Appliance also has capability flags for remote shell, code execution, maintenance, simulator control, MoveIt management, Nav2 management, log streaming, topic throttling, remapping, and general settings. These flags control Appliance and Portal management operations. They do not add methods to the SDK API. GET /capabilities and the capabilities field in GET /health report that management surface to the Portal.

For hardened deployments, review the Appliance release configuration before enabling management operations or making any listener network-accessible.