Quickstart

Get the full RosFit platform running locally in under 5 minutes. By the end of this guide you will have a running dashboard, a registered device, and will have sent your first remote command.

Prerequisites

Before you begin, make sure the following tools are installed on your machine:

• Docker — v20.10 or later
• Docker Compose — v2.0 or later (included with Docker Desktop)
• Git — any recent version
• A ROS 2 robot — optional for this guide; you can test with simulated telemetry

Start the stack

Clone the repository and bring up every service with a single command:

git clone https://github.com/rosfit/rosfit.git
cd rosfit
cp .env.example .env
docker compose up -d

This starts the following services:

Wait about 30 seconds for all services to become healthy, then verify:

docker compose ps

Every service should show running (healthy).

Open dashboard

Open your browser and navigate to:

http://localhost:3000

You will see the RosFit fleet dashboard. It is empty for now — let's fix that by registering your first device.

Register a device

Use the REST API to register a new device. Replace the name and type with your own values if you like:

curl -X POST http://localhost:8000/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{
    "name": "turtlebot-01",
    "type": "ros2_robot",
    "description": "TurtleBot 3 in the lab",
    "tags": ["lab", "navigation"]
  }'

The API returns a JSON response containing the new device's id and an MQTT access_token. Save both — you will need them in the next step.

{
  "id": "dev_abc123",
  "name": "turtlebot-01",
  "type": "ros2_robot",
  "access_token": "mqtt_tok_xxxxx",
  "status": "provisioning",
  "created_at": "2026-03-30T10:00:00Z"
}

Install bridge on robot

On your robot (or any machine running ROS 2), install the RosFit bridge:

pip install rosfit-bridge

Create a bridge configuration file called bridge.yaml:

device_id: dev_abc123
mqtt:
  host: 192.168.1.100   # IP of the machine running docker compose
  port: 1883
  token: mqtt_tok_xxxxx

bridges:
  - ros_topic: /odom
    mqtt_topic: rosfit/dev_abc123/telemetry/odom
    direction: ros_to_mqtt
    qos: 1
  - ros_topic: /cmd_vel
    mqtt_topic: rosfit/dev_abc123/command/cmd_vel
    direction: mqtt_to_ros
    qos: 1
  - ros_topic: /scan
    mqtt_topic: rosfit/dev_abc123/telemetry/scan
    direction: ros_to_mqtt
    qos: 0

Start the bridge:

rosfit bridge start --config bridge.yaml

Within seconds, your device will appear as online in the dashboard and telemetry will begin streaming.

Send a command

Send a velocity command to your robot through the API:

curl -X POST http://localhost:8000/api/v1/commands/dev_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "command": "cmd_vel",
    "data": {
      "linear": { "x": 0.2, "y": 0.0, "z": 0.0 },
      "angular": { "x": 0.0, "y": 0.0, "z": 0.5 }
    }
  }'

The command is routed through MQTT to the bridge, which publishes it as a ROS 2 Twist message on /cmd_vel. You can also send commands directly from the dashboard's command panel.

What's next

You have a running RosFit stack, a registered device, and you have sent your first command. Here are some suggested next steps: