Installation

Requirements

  • Python 3.10+

  • Docker (images are pulled automatically from Docker Hub)

  • (Optional but recommended) NVIDIA GPU with CUDA 12.1+ for faster policy inference

    • CPU-only mode is supported but will be significantly slower

    • NVIDIA Container Toolkit required only if using GPU acceleration

Install from PyPI

pip install maple-robotics

Install from Source

git clone https://github.com/Shaswat2001/maple-robotics.git
cd maple-robotics
pip install -e .

Optional Dependencies

For development:

pip install maple-robotics[dev]

For documentation:

pip install maple-robotics[docs]

Docker Setup

Maple uses Docker to run policies and environments in isolated containers. Docker images are automatically pulled from Docker Hub when you first use a policy or environment.

1. Install Docker

Follow the official Docker installation guide for your OS: https://docs.docker.com/get-docker/

GPU Acceleration (Optional)

For significantly faster policy inference, GPU acceleration is recommended.

Note

CPU-only inference is supported but can be 10-100x slower depending on the policy. Only install GPU support if you have an NVIDIA GPU.

1. Install NVIDIA Container Toolkit

Only required if you want GPU acceleration.

For GPU support with NVIDIA GPUs:

# Add the package repositories
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# Install nvidia-docker2
sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

2. Verify GPU Access

docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi

You should see your GPU information.

Verify Installation

# Check CLI is available
maple --help

# Start daemon and check status
maple serve &
maple status

# You should see:
# VLA daemon running
#   Port: 8000
#   Device: cuda:0  (or cpu if no GPU)

Docker Image Management

Policy and environment Docker images are automatically pulled from Docker Hub when needed.

# Images are pulled automatically on first use
# For example, when you first run:
maple pull openvla:latest  # Pulls maple/openvla:latest from Docker Hub

Available Pre-built Images

The following images are available on Docker Hub:

  • maplerobotics/openvla:latest - OpenVLA policy

  • maplerobotics/smolvla:latest - SmolVLA policy

  • maplerobotics/libero:latest - LIBERO environment

You can also pull images manually:

docker pull maplerobotics/openvla:latest
docker pull maplerobotics/smolvla:latest
docker pull maplerobotics/libero:latest

Building Custom Images (Advanced)

Only needed if you want to modify the Docker images.

If you need to customize the policy or environment containers, you can build images locally:

# Build OpenVLA policy image
docker build -t maple/openvla:latest docker/openvla/

# Build SmolVLA policy image
docker build -t maple/smolvla:latest docker/smolvla/

# Build LIBERO environment image
docker build -t maple/libero:latest docker/libero/

Troubleshooting

Docker Permission Issues

If you get permission errors when running Docker commands:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and log back in for changes to take effect

Disk Space

Docker images can be large (several GB). Ensure you have sufficient disk space:

# Check Docker disk usage
docker system df

# Clean up unused images
docker system prune -a

CPU vs GPU Performance

Expected inference times (approximate):

  • GPU (NVIDIA RTX 3090): 10-50ms per inference

  • CPU (Intel i9): 500-2000ms per inference

For interactive control or real-time applications, GPU acceleration is strongly recommended.