Quickstart

Get TraceHouse™ running on your robot in minutes.

:::info Prerequisites

• Ubuntu 24.04 Noble (ROS 2 Jazzy) — or Ubuntu 22.04 Jammy (ROS 2 Humble, arm64 / Jetson). See system requirements
• ROS 2 installed and sourced
• sudo access on the robot's onboard computer (not needed inside most containers, which run as root)
• A TraceHouse account and API key — sign up at robotops.com :::

1. Install

Run the installer on your robot:

curl -fsSL https://www.robotops.com/install.sh | bash

The script adds the apt.robotops.com repository and installs, for your detected ROS distro:

• robot-agent — the telemetry agent (binary at /usr/bin/robot-agent)
• rmw_robotops + robotops_msgs + robotops_config — the distributed-tracing middleware

Installing rmw_robotops does not turn tracing on — that's a runtime opt-in (step 3). It just makes the middleware available so RMW_IMPLEMENTATION=rmw_robotops resolves out of the box. Pass ROBOTOPS_SKIP_RMW=1 to install the agent only.

What's in this script?

The installer performs these steps — no surprises:

# Add the RobotOps GPG key
curl -fsSL https://apt.robotops.com/robotops-public-key.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/robotops-archive-keyring.gpg

# Add the apt repository (suite = your Ubuntu codename, e.g. noble)
echo "deb [signed-by=/usr/share/keyrings/robotops-archive-keyring.gpg] https://apt.robotops.com noble main" \
  | sudo tee /etc/apt/sources.list.d/robotops.list

sudo apt update

# Agent (Jazzy — amd64 + arm64; Jetson/Humble arm64: robot-agent-humble)
sudo apt install -y robot-agent-jazzy

# Distributed-tracing middleware (per distro)
sudo apt install -y ros-jazzy-rmw-robotops ros-jazzy-robotops-msgs ros-jazzy-robotops-config

You can also run these steps manually if you prefer not to pipe scripts.

2. Configure

The agent is configured entirely through environment variables — the same set, regardless of how you run it:

Variable	Required?	Value
ROBOTOPS_API_KEY	Yes	Your key (sk_…) from the dashboard
ROBOT_OPS_AGENT_BACKEND_URL	Recommended	https://backend.robotops.com (the production endpoint)
RMW_IMPLEMENTATION	Optional	rmw_robotops to enable distributed tracing (step 3)
ROBOTOPS_UNDERLYING_RMW	Optional	Your existing DDS, e.g. rmw_fastrtps_cpp

:::note Why set ROBOT_OPS_AGENT_BACKEND_URL explicitly? The agent's built-in default still points at the legacy api.robotops.com host. Setting the backend URL pins you to the canonical production endpoint, backend.robotops.com. It's a normal override — point it anywhere for self-hosted or local development (e.g. http://localhost:50051). :::

3. Run

Only ROBOTOPS_API_KEY is needed to start streaming. Pick the model that matches your deployment — the agent reads the same variables either way.

On-host (systemd)

For a permanent install on a robot's onboard computer. The Debian package ships a robot-agent systemd unit; configure it with an override:

sudo systemctl edit robot-agent

Add your variables under [Service]:

[Service]
Environment=ROBOTOPS_API_KEY=sk_your_api_key_here
Environment=ROBOT_OPS_AGENT_BACKEND_URL=https://backend.robotops.com
# distributed tracing — optional, recommended:
Environment=RMW_IMPLEMENTATION=rmw_robotops
Environment=ROBOTOPS_UNDERLYING_RMW=rmw_fastrtps_cpp

Then enable and start it:

sudo systemctl enable --now robot-agent
sudo systemctl status robot-agent

Container (Docker)

Inside a container, don't use systemd — pass the variables with -e and run the agent as a plain process (alongside your ROS 2 nodes, or from your launch file's telemetry step):

docker run --rm -it \
  --net=host --ipc=host \
  -e ROBOTOPS_API_KEY=sk_your_api_key_here \
  -e ROBOT_OPS_AGENT_BACKEND_URL=https://backend.robotops.com \
  -e RMW_IMPLEMENTATION=rmw_robotops \
  -e ROBOTOPS_UNDERLYING_RMW=rmw_fastrtps_cpp \
  your-image robot-agent

Setting RMW_IMPLEMENTATION at the container level means every ROS 2 node in the container inherits the tracing middleware. Build the agent + rmw_robotops into your image by adding the one-liner to your Dockerfile (see the reference image).

Quick test (foreground)

To try it out without a process manager, set the variables inline and run the binary directly:

ROBOTOPS_API_KEY=sk_your_api_key_here \
ROBOT_OPS_AGENT_BACKEND_URL=https://backend.robotops.com \
robot-agent

Add RMW_IMPLEMENTATION=rmw_robotops and ROBOTOPS_UNDERLYING_RMW=rmw_fastrtps_cpp to the same line to include distributed tracing. robot-agent --help lists all flags; robot-agent upgrade checks installed versions.

4. Enable distributed tracing (recommended)

rmw_robotops wraps your existing DDS middleware to propagate OpenTelemetry-compatible trace context through every ROS 2 message. The package is already installed (step 1) — you enable it by setting two environment variables wherever your nodes launch:

• RMW_IMPLEMENTATION=rmw_robotops
• ROBOTOPS_UNDERLYING_RMW=<your current DDS> (e.g. rmw_fastrtps_cpp, rmw_cyclonedds_cpp)

:::note Enable it where your nodes launch, not just on the agent RMW_IMPLEMENTATION must be set in the environment of the ROS 2 nodes you want traced — not only the agent. Set it in the systemd override (on-host), the docker run -e flags (container, applies to all nodes), or directly in your launch file with a SetEnvironmentVariable action. rmw_robotops delegates all real communication to ROBOTOPS_UNDERLYING_RMW and only adds tracing on top — nodes without it still interoperate normally. :::

5. Verify

You should see the agent discover ROS 2 topics and begin streaming telemetry. Data appears in your TraceHouse dashboard within a few seconds.

On-host (systemd)

sudo systemctl status robot-agent      # is it running?
sudo journalctl -u robot-agent -f      # follow live logs

Container (Docker)

docker logs -f <container>             # agent logs go to the container's stdout

Quick test (foreground)

The agent logs directly to your terminal — watch for topic discovery and "streaming" lines.

---

Manual install

If you prefer to install without piping the script, run each step individually:

# 1. Add the GPG key
curl -fsSL https://apt.robotops.com/robotops-public-key.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/robotops-archive-keyring.gpg

# 2. Add the repository
echo "deb [signed-by=/usr/share/keyrings/robotops-archive-keyring.gpg] https://apt.robotops.com noble main" \
  | sudo tee /etc/apt/sources.list.d/robotops.list

# 3. Install the agent + tracing middleware (Jazzy; Jetson/Humble: swap jazzy→humble)
sudo apt update
sudo apt install robot-agent-jazzy \
  ros-jazzy-rmw-robotops ros-jazzy-robotops-msgs ros-jazzy-robotops-config

Then configure and run it using one of the models in step 3.

Installing via rosdep / ament

If your team manages dependencies declaratively, you can pull rmw_robotops the ament-native way instead of apt install-ing it directly. Add the apt repository (step 1 of the manual install), then declare the packages as run dependencies in your package.xml:

<exec_depend>rmw_robotops</exec_depend>
<exec_depend>robotops_msgs</exec_depend>
<exec_depend>robotops_config</exec_depend>

rosdep install --from-paths src --ignore-src -y then resolves them from apt.robotops.com. This is still a runtime middleware swap — you do not link rmw_robotops into your packages or rebuild them; you only need the package present and RMW_IMPLEMENTATION=rmw_robotops set at launch.

caution

The rosdep keys currently resolve to the Jazzy packages only. On Humble, install the ros-humble-* packages directly (manual install above) until distro-aware keys land.

The robot-agent daemon itself is infrastructure, not a ROS node — install it via the script or apt, never as an ament dependency.

What's next

• System Requirements — hardware, OS, and distro details
• TraceHouse Agent Overview — what the agent collects and how to configure it
• Features & Configuration — capture strategies, env vars, config file
• ROSQL — query your telemetry with the open source query language