🤖 Agent ROS Bridge

Universal ROS1/ROS2 bridge for AI agents to control robots and embodied intelligence systems.


---

🔐 Security-First Design

JWT authentication is always required and cannot be disabled.

# Generate a secure secret (REQUIRED - no exceptions)
export JWT_SECRET=$(openssl rand -base64 32)

The bridge will fail to start without JWT_SECRET. This is by design — security is not optional.

See SECURITY.md for complete security guidelines.

---

Quick Start

Option 1: Docker Examples (Recommended for Testing)

All examples run in isolated Docker containers with simulated robots (no ROS installation needed).

# Clone repository
git clone https://github.com/webthree549-bot/agent-ros-bridge.git
cd agent-ros-bridge

# Generate JWT secret
export JWT_SECRET=$(openssl rand -base64 32)

# Run example in Docker
cd examples/quickstart
docker-compose up

# Test connection
curl http://localhost:8765/health

Available Examples

Example	Description	Run
examples/quickstart/	Basic bridge with simulated robot	docker-compose up
examples/fleet/	Multi-robot fleet coordination	docker-compose up
examples/arm/	Robot arm control simulation	docker-compose up

All examples:

• Run in isolated Docker containers
• Use JWT authentication (enforced)
• Include simulated robots (no hardware needed)
• Bind to localhost (127.0.0.1) by default

Option 2: Native Installation (Production)

Requirements: Ubuntu 20.04/22.04 with ROS1 Noetic or ROS2 Humble/Jazzy

# Install from PyPI
pip install agent-ros-bridge

# Set required secret
export JWT_SECRET=$(openssl rand -base64 32)

# Start bridge
agent-ros-bridge --config config/bridge.yaml

See docs/NATIVE_ROS.md for detailed native installation.

---

Features

Feature	Description
🔐 Security	JWT auth always required, no bypass
🤖 Multi-Robot	Fleet orchestration & coordination
🌐 Multi-Protocol	WebSocket, MQTT, gRPC
🔄 Multi-ROS	ROS1 + ROS2 simultaneously
🦾 Arm Control	UR, xArm, Franka support
📊 Monitoring	Prometheus + Grafana

---

Documentation

Document	Description
User Manual	Complete guide (23,000+ words)
API Reference	Full API documentation
Native ROS	Ubuntu/ROS installation
Docker vs Native	Deployment comparison
SECURITY.md	Security policy

---

Usage

Python API

from agent_ros_bridge import Bridge
from agent_ros_bridge.gateway_v2.transports.websocket import WebSocketTransport

# Bridge requires JWT_SECRET env var
bridge = Bridge()
bridge.transport_manager.register(WebSocketTransport({"port": 8765}))
await bridge.start()

CLI

# Set required secret
export JWT_SECRET=$(openssl rand -base64 32)

# Start bridge
agent-ros-bridge --config config/bridge.yaml

# Generate token for client
python scripts/generate_token.py --secret $JWT_SECRET --role operator

---

Links

• Documentation: https://github.com/webthree549-bot/agent-ros-bridge/tree/main/docs
• PyPI: https://pypi.org/project/agent-ros-bridge/
• GitHub: https://github.com/webthree549-bot/agent-ros-bridge
• Issues: https://github.com/webthree549-bot/agent-ros-bridge/issues

---

Security is not optional. JWT auth always required.