README.md

---
title: LeRobot Arena
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
suggested_hardware: cpu-upgrade
suggested_storage: small
short_description: A web-based robotics control
tags:
  - robotics
  - control
  - simulation
  - websocket
  - fastapi
  - svelte
  - urdf
  - 3d-visualization
pinned: true
fullWidth: true
---

# 🤖 LeRobot Arena

A web-based robotics control and simulation platform that bridges digital twins and physical robots. Built with Svelte for the frontend and FastAPI for the backend.

## 🚀 Quick Start with Docker

The easiest way to run LeRobot Arena is using Docker, which sets up both the frontend and backend automatically.

### Prerequisites

- [Docker](https://www.docker.com/get-started) installed on your system
- [Docker Compose](https://docs.docker.com/compose/install/) (usually included with Docker Desktop)

### Step-by-Step Instructions

1. **Clone the repository**

   ```bash
   git clone <your-repo-url>
   cd lerobot-arena
   ```

2. **Build and start the services**

   ```bash
   docker-compose up --build
   ```

3. **Access the application**

   - **Frontend**: http://localhost:7860
   - **Backend API**: http://localhost:8080
   - **API Documentation**: http://localhost:8080/docs

4. **Stop the services**
   ```bash
   # Press Ctrl+C to stop, or in another terminal:
   docker-compose down
   ```

### Alternative Docker Commands

If you prefer using Docker directly:

```bash
# Build the image
docker build -t lerobot-arena .

# Run the container
docker run -p 7860:7860 lerobot-arena
```

## 🛠️ Development Setup

For local development with hot-reload capabilities:

### Frontend Development

```bash
# Install dependencies
bun install

# Start the development server
bun run dev

# Or open in browser automatically
bun run dev -- --open
```

### Backend Development

```bash
# Navigate to Python backend
cd src-python

# Install Python dependencies (using uv)
uv sync

# Or using pip
pip install -e .

# Start the backend server
python start_server.py
```

### Building Standalone Executable

The backend can be packaged as a standalone executable using box-packager:

```bash
# Navigate to Python backend
cd src-python

# Install box-packager (if not already installed)
uv pip install box-packager

# Package the application
box package

# The executable will be in target/release/lerobot-arena-server
./target/release/lerobot-arena-server
```

Note: Requires [Rust/Cargo](https://rustup.rs/) to be installed for box-packager to work.

## 📋 Project Structure

```
lerobot-arena/
├── src/                    # Svelte frontend source
│   ├── lib/               # Reusable components and utilities
│   ├── routes/            # SvelteKit routes
│   └── app.html           # App template
├── src-python/            # Python backend
│   ├── src/               # Python source code
│   ├── start_server.py    # Server entry point
│   ├── target/            # Box-packager build output (excluded from git)
│   └── pyproject.toml     # Python dependencies
├── static/                # Static assets
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Docker Compose setup
└── package.json           # Node.js dependencies
```

## 🐳 Docker Information

The Docker setup includes:

- **Multi-stage build**: Optimized for production using Bun and uv
- **Automatic startup**: Both services start together
- **Port mapping**: Backend on 8080, Frontend on 7860 (HF Spaces compatible)
- **Static file serving**: Compiled Svelte app served efficiently
- **User permissions**: Properly configured for Hugging Face Spaces
- **Standalone executable**: Backend packaged with box-packager for faster startup

For detailed Docker documentation, see [DOCKER_README.md](./DOCKER_README.md).

## 🔧 Building for Production

### Frontend Only

```bash
bun run build
```

### Backend Standalone Executable

```bash
cd src-python
box package
```

### Complete Docker Build

```bash
docker-compose up --build
```

## 🌐 What's Included

- **Real-time Robot Control**: WebSocket-based communication
- **3D Visualization**: Three.js integration for robot visualization
- **URDF Support**: Load and display robot models
- **Multi-robot Management**: Control multiple robots simultaneously
- **WebSocket API**: Real-time bidirectional communication
- **Standalone Distribution**: Self-contained executable with box-packager

## 🚨 Troubleshooting

### Port Conflicts

If ports 8080 or 7860 are already in use:

```bash
# Check what's using the ports
lsof -i :8080
lsof -i :7860

# Use different ports
docker run -p 8081:8080 -p 7861:7860 lerobot-arena
```

### Container Issues

```bash
# View logs
docker-compose logs lerobot-arena

# Rebuild without cache
docker-compose build --no-cache
docker-compose up
```

### Development Issues

```bash
# Clear node modules and reinstall
rm -rf node_modules
bun install

# Clear Svelte kit cache
rm -rf .svelte-kit
bun run dev
```

### Box-packager Issues

```bash
# Clean build artifacts
cd src-python
box clean

# Rebuild executable
box package

# Install cargo if missing
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

## 🚀 Hugging Face Spaces Deployment

This project is configured for deployment on Hugging Face Spaces:

1. **Fork** this repository to your GitHub account
2. **Create a new Space** on Hugging Face Spaces
3. **Connect** your GitHub repository
4. **Select Docker SDK** (should be auto-detected from the frontmatter)
5. **Deploy** - The Space will automatically build and run

The frontend will be available at your Space URL, and the backend API will be accessible at `/api/` endpoints.

## 📚 Additional Documentation

- [Docker Setup Guide](./DOCKER_README.md) - Detailed Docker instructions
- [Robot Architecture](./ROBOT_ARCHITECTURE.md) - System architecture overview
- [Robot Instancing Guide](./ROBOT_INSTANCING_README.md) - Multi-robot setup

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Docker: `docker-compose up --build`
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License.

---

**Built with ❤️ for the robotics community** 🤖