TPT SwarmOS

The open-source "Linux of physical robotics" — a hardware-agnostic middleware and AI control layer for orchestrating fleets of humanoid robots and drones.

What it does

Universal robot adapter — one platform for Boston Dynamics, Tesla Optimus, agricultural drones, and any ROS2-compatible hardware
Simulation-to-deployment — train skills in Gazebo, deploy to any robot in the fleet instantly
Federated learning — a robot in Tokyo learns a better way to fold laundry; every robot in the network gets the update
Decentralized — open hardware collectives and municipalities run their own autonomous workforce without depending on tech monopolies

Architecture

tpt-swarm/
├── swarm-core/          ← Rust: lightweight on-robot agent (ROS2, ONNX, P2P)
├── swarm-orchestrator/  ← Go: fleet API, skill registry, FedAvg coordinator
├── swarm-dashboard/     ← TypeScript/React: fleet + skills + simulation + federated UI
├── sim/                 ← Gazebo worlds, URDF robot templates, launch files
└── proto/               ← Protobuf contracts shared between core and orchestrator

Stack

Component	Technology
Robot agent	Rust + r2r (ROS2) + ort (ONNX)
Fleet orchestrator	Go + Echo + gRPC + PostgreSQL
P2P gossip	libp2p (Rust + Go)
Federated learning	FedAvg aggregation + P2P fallback
Skill format	ONNX + manifest.yaml
Simulation	Gazebo + ROS2
Dashboard	Vite + React + TypeScript + shadcn/ui

Quick Start

# Start orchestrator + database + dashboard
docker-compose up

# Launch a simulated fleet (requires ROS2 + Gazebo installed)
ros2 launch sim/launch/sim_launch.py world:=warehouse robot_count:=3

# Open dashboard
open http://localhost:5173

Skill Format

A SwarmOS skill is an ONNX model paired with a manifest:

# manifest.yaml
name: "warehouse-navigation"
version: "1.0.0"
input_schema:
  - name: joint_states
    shape: [1, 12]
    dtype: float32
  - name: lidar_scan
    shape: [1, 360]
    dtype: float32
output_schema:
  - name: cmd_vel
    shape: [1, 2]
    dtype: float32
hardware_requirements:
  min_dof: 6
  sensors: [lidar, imu]

License

Apache 2.0

Platform Architecture

                    ┌─────────────────────────────────────────────────┐
                    │                SwarmOS Platform                 │
                    │                                                  │
  Browser           │  ┌──────────────┐    ┌───────────────────────┐  │
  Dashboard ────────┼──│   Dashboard  │    │     Orchestrator       │  │
  (React/TS)        │  │ (nginx:5173) │────│  HTTP :8080            │  │
                    │  └──────────────┘    │  gRPC :9090            │  │
                    │                      │  P2P  :4001            │  │
  Robot Agents      │                      │  PostgreSQL            │  │
  (Rust binary) ────┼──────────────────────│  Federated Aggregator  │  │
  gRPC heartbeat    │                      └───────────────────────┘  │
  P2P gossip        │                                                  │
                    │  ┌──────────────────────────────────────────┐   │
                    │  │           Simulation (optional)           │   │
                    │  │  Gazebo + ROS2 → sim_launch.py            │   │
                    │  └──────────────────────────────────────────┘   │
                    └─────────────────────────────────────────────────┘

Quickstart Without Hardware

No robot? No ROS2? No problem. The demo stack spins up the full platform with 4 software-simulated agents sending synthetic telemetry.

Prerequisites: Docker + Docker Compose

# Clone the repo
git clone https://github.com/tpt-swarm/tpt-swarm.git
cd tpt-swarm

# Start everything (postgres + orchestrator + mock agents + dashboard)
docker compose -f docker-compose.demo.yml up --build

# Open the dashboard
open http://localhost:5173

The mock agents register, send heartbeats every 500 ms, accept skill deploy commands, and report completion after 10 seconds — enough to exercise the full orchestration loop without any hardware.

To stop and clean up:

docker compose -f docker-compose.demo.yml down -v

Or use the Makefile shortcuts:

make demo       # start
make demo-down  # stop + remove volumes

Running a Real Agent

1. Build the Rust agent

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

cd swarm-core
cargo build --release
# Binary: target/release/agent

2. Configure the agent

cp swarm-agent.toml.example swarm-agent.toml

Edit swarm-agent.toml to point at your orchestrator and set your ROS2 namespace:

orchestrator_addr = "http://<orchestrator-ip>:9090"
ros2_namespace    = "robot"           # matches /robot/cmd_vel etc.
skill_cache_dir   = "/tmp/swarm-skills"
heartbeat_interval_ms = 500

3. Start the orchestrator (if not already running)

# Copy and edit environment overrides
cp .env.example .env

docker compose up postgres orchestrator -d

4. Run the agent on your robot

# Requires ROS2 Humble sourced in the shell
source /opt/ros/humble/setup.bash

./swarm-core/target/release/agent --config swarm-agent.toml

The agent self-registers and appears in the dashboard within a few seconds.

swarm-ctl CLI

swarm-ctl is a lightweight CLI for interacting with the orchestrator REST API.

# Run directly with Go
go run ./swarm-orchestrator/tools/swarm-ctl/ [command]

# Or build it
cd swarm-orchestrator && go build -o swarm-ctl ./tools/swarm-ctl/

Environment variables:

Variable	Default	Description
`SWARM_URL`	`http://localhost:8080`	Orchestrator base URL
`SWARM_API_KEY`	(empty)	API key (if auth is enabled)

Commands:

# List all connected robots
swarm-ctl robots list

# Get details for a specific robot
swarm-ctl robots get <robot-id>

# List registered skills
swarm-ctl skills list

# Upload a new skill (ONNX model + manifest)
swarm-ctl skills upload model.onnx manifest.yaml --name warehouse-nav --version 1.0.0

# Deploy a skill to one or more robots
swarm-ctl skills deploy <skill-id> <robot-id> [robot-id...]

# Fleet summary (online count, battery averages, active skills)
swarm-ctl fleet status

# List federated learning aggregation rounds
swarm-ctl federated rounds

Development Setup

Run the full prerequisite check and build all components:

# Linux / macOS
bash scripts/setup.sh

# Windows (PowerShell)
.\scripts\quickstart.ps1

Or install the pre-commit hook to catch issues before every commit:

bash scripts/install-hooks.sh

The hook runs buf lint, go vet, cargo clippy, and a dashboard type-check.

Useful Makefile targets

Target	Description
`make proto`	Regenerate protobuf code from `proto/`
`make build`	Build all three components
`make dev`	Start postgres+orchestrator in Docker, Vite locally
`make demo`	Full demo stack with mock agents
`make test`	Run Go + Rust tests
`make smoke`	End-to-end smoke test via Docker
`make clean`	Remove build artifacts

Troubleshooting

Port 8080 already in use Set HTTP_ADDR=0.0.0.0:8081 in your .env file (or pass it to docker compose), then update VITE_ORCHESTRATOR_URL in the dashboard env accordingly.

postgres fails to start Check that port 5432 is not already occupied by another PostgreSQL instance (lsof -i :5432 or netstat -ano | findstr 5432). Volume permission errors on Linux can be fixed with sudo chown -R $USER docker-volumes/.

Agent can't connect to orchestrator Verify orchestrator_addr in swarm-agent.toml uses the gRPC port (9090), not the HTTP port. Example: http://192.168.1.10:9090. Ensure the orchestrator container's port 9090 is published.

ROS2 not found The Rust agent's ros2-bridge crate requires ROS2 Humble (or later) installed and sourced (source /opt/ros/humble/setup.bash). Simulation via sim_launch.py additionally requires Gazebo. Both are Linux-only. The mock-agent and orchestrator run without ROS2.

buf generate fails Install the buf CLI from https://buf.build/docs/installation, then rerun make proto. Ensure buf is on your PATH.

Dashboard shows "Reconnecting…" The dashboard lost its WebSocket connection to the orchestrator. Check that the orchestrator is running (docker compose ps) and that VITE_WS_URL in swarm-dashboard/.env.local matches the actual host and port (default ws://localhost:8080). CORS issues can also cause this — set CORS_ALLOW_ORIGINS on the orchestrator to match the dashboard origin.

tpt-swarm

Languages