Important

This repository is currently in Developer Preview mode and not ready for production use. There may be bugs, and APIs and configuration options are subject to change during this period.

ROS Portal

ROS Portal connects a ROS 2 graph to other LiveKit participants (ROS 2 or not) through LiveKit's real-time network, enabling access to a ROS graph from anywhere in the world. It forwards configured ROS topics as schema-described LiveKit DataTracks, republishes allowed remote tracks back into ROS, forwards configured service calls over LiveKit RPC, and streams sensor_msgs/msg/Image topics as LiveKit video. ROS Portal enables low-latency teleoperation, monitoring, and robot-to-cloud communication without exposing DDS across networks.

Quick Start

1. Install ROS Portal. Download the .deb for your ROS 2 distro and architecture and install. See Installation.
2. Configure ROS Portal. Set LiveKit credentials and a YAML config for the topics and services to forward. See Configuration.
3. Run ROS Portal. Start a LiveKit server or connect to your LiveKit Cloud project, then run. See Running.

Or run the same node from the multi-architecture Docker image for your ROS distribution:

docker run --rm \
  --network host \
  --env LIVEKIT_URL=<url> \
  --env LIVEKIT_TOKEN=<token> \
  --volume /path/on/host/config.yaml:/config/ros_portal.yaml:ro \
  livekit/ros-portal:jazzy \
  ros2 launch ros_portal ros_portal.launch.py \
  config_path:=/config/ros_portal.yaml

Images are available for Humble, Jazzy, Kilted, and Lyrical on amd64 and arm64. See Running with Docker for tags, networking, and release details.

To get familiar with using ROS Portal after that, follow the tutorials.

User Guides

• Installation: Installing LiveKit dependencies and ROS Portal.
• Configuration: Configuring LiveKit environment variables and the ROS Portal configuration file.
• Running: Running ROS Portal against LiveKit Cloud or local server.
• Remote ROS2 CLI calls: Remote ros2 command services backed by LiveKit RPC.
• Diagnostics: /diagnostics fields and aggregator setup.

Developer Guides

• Development: devcontainer layout, SSH agent forwarding, Docker image caching, and C++ tooling.
• Testing: unit and integration test commands and required LiveKit test environment.
• Current limitations: known implementation limits and follow-up work.

Design Reference

• Architecture: ROS Portal data flow, LiveKit DataTracks, LiveKit RPC, message paths, and QoS selection.
• Data-track schemas: ROS message schema transport, registration, validation, and failure behavior.

Packages of Interest

• ros_portal: ROS Portal node, launch files, default config, and ROS Portal-specific tests.
• ros_portal_config: schema-driven YAML config parser and generated C++ config types.
• ros_portal_msgs: custom service interfaces for remote ros2 CLI operations.
• ros_portal_tutorials: tutorials for using ROS Portal in a variety of scenarios.

Other package READMEs under src/ document package-specific setup, fixtures, and examples.

Robots

Complete robot stacks that consume ROS Portal live in their own repositories, so that hardware-specific drivers, launch trees, and container images stay out of this one:

• cobra_flex_ros: teleoperation for the Waveshare Cobra Flex rover.
• waver_ros: teleoperation and autonomous navigation for the 4-wheeled Waveshare WAVE ROVER on a Raspberry Pi.