Quickstart

Get TraceHouse™ running on your robot in minutes.

:::info Prerequisites

• Ubuntu 24.04 Noble — see system requirements
• ROS2 Jazzy installed and sourced
• sudo access on the robot's onboard computer
• A TraceHouse account and API key — sign up at robotops.com :::

1. Install the TraceHouse agent

Run the installer on your robot:

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

The script adds the apt.robotops.com repository, installs the robot-agent Debian package, and prints next steps.

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
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

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

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

2. Configure your API key

The agent needs your TraceHouse API key to ship data. Edit the systemd service override:

sudo systemctl edit robot-agent

Add the following under [Service]:

[Service]
Environment=ROBOTOPS_API_KEY=sk_your_api_key_here

Save and close. You can find your API key in the TraceHouse dashboard.

3. Enable distributed tracing (recommended)

rmw_robotops wraps your existing DDS middleware to propagate OpenTelemetry-compatible trace context through every ROS2 message. Enable it by adding two more environment variables to your systemd override:

sudo systemctl edit robot-agent

[Service]
Environment=ROBOTOPS_API_KEY=sk_your_api_key_here
Environment=RMW_IMPLEMENTATION=rmw_robotops
Environment=ROBOTOPS_UNDERLYING_RMW=rmw_fastrtps_cpp

note

Set ROBOTOPS_UNDERLYING_RMW to whatever DDS middleware you currently use (e.g. rmw_cyclonedds_cpp). rmw_robotops delegates all real communication to it and only adds tracing on top.

4. Start the agent

sudo systemctl enable --now robot-agent

5. Verify

# Check the service is running
sudo systemctl status robot-agent

# Follow live logs
sudo journalctl -u robot-agent -f

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

---

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 (Jazzy — amd64 + arm64; Jetson/Humble arm64: robot-agent-humble)
sudo apt update
sudo apt install robot-agent-jazzy

# 4. Enable the service
sudo systemctl enable --now robot-agent

What's next

• System Requirements — hardware, OS, and distro details
• TraceHouse Agent Overview — what the agent collects and how to configure it
• ROSQL — query your telemetry with the open source query language