simup: One-Click MuJoCo on Azure ML

simup ("my sim is up") is a simple CLI for deploying MuJoCo simulation environments on Azure ML. One command, and your sim is up.

Why This Exists

MuJoCo is a beautiful physics engine with an elegant API. But We hit surprising issues deploying it on Azure ML. We doumented the painful journey in our blog post Deploying MuJoCo on Azure ML and this simup is how we share a wrapper that helps people avoid these issues.

The goal is that simup deploy should be as easy as pip install for deploying MuJoCo on Azure ML.

What You Get from simup

A headless VM in the cloud with everything pre-installed:

• MuJoCo physics engine
• dm_control humanoid demo (21 actuators, 17 bodies, 22 joints)
• Jupyter Lab in your browser for interactive simulation
• Example scripts for video rendering and benchmarking

Important: The VM has no monitor or GUI. (It's a cloud server, not a gaming PC.) You interact via:

1. Jupyter Lab (browser) -- best for interactive work and inline video
2. SSH -- run scripts, render video to MP4, download via simup download

Prerequisites

Before you start, make sure you have:

1. Python 3.10+ (check with python3 --version)
2. Azure CLI installed (install guide)
3. Azure account with an active subscription
4. SSH key (~/.ssh/id_rsa by default, or specify with --ssh-key)

That's the whole list. No GPU quota needed if you start with --preset cpu.

Finding your Subscription ID and Resource Group

simup needs two things from your Azure account: a Subscription ID and a Resource Group. If you're coming from AWS or GCP, here's the translation:

To find your Subscription ID:

• Go to portal.azure.com > Subscriptions > copy the Subscription ID
• Or run: az account show --query id -o tsv

To find or create a Resource Group:

• Go to portal.azure.com > Resource groups
• Or create one: az group create --name my-mujoco-rg --location eastus

Quick Start

Setup takes 5-10 minutes after the VM starts. Monitor progress:

simup ssh <name>
tail -f /var/log/simup-setup.log

# 1. Authenticate with Azure
az login

# 2. Clone and install
git clone https://github.com/Haptic-AI/one-click-mujoco-azure.git
cd one-click-mujoco-azure
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 3. Configure (replace with your values)
simup config --subscription YOUR_SUBSCRIPTION_ID --resource-group YOUR_RG
simup config --ssh-key ~/.ssh/mykey   # optional, defaults to ~/.ssh/id_rsa

# 4. Check everything is ready
simup preflight

# 5. Deploy
simup deploy --preset cpu             # CPU (~$0.19/hr, no GPU quota needed)
simup deploy                          # medium T4 GPU (default, ~$0.75/hr, requires GPU quota)
simup deploy --dry-run                # preview without creating

Viewing Your Simulation

The VM is headless -- there is no display window. Here's how to see your work:

Option 1: Jupyter Lab (recommended)

simup jupyter <name> --open

Opens Jupyter Lab in your browser. The demo notebook renders video inline -- no file downloads needed. You'll see the humanoid. It'll be standing there. It's beautiful.

Option 2: Render + Download

# SSH in and render a video
simup ssh <name>
python3 robot/simulate.py --video
# Video saved to /tmp/humanoid_sim.mp4 on the VM
exit

# Download it (this is why we built simup -- beats writing scp commands by hand)
simup download <name> /tmp/humanoid_sim.mp4 ./
open humanoid_sim.mp4

The simup CLI

VM Presets

VMs bill while running. Run simup destroy <name> when done.

Most users should start with cpu. MuJoCo works fine without a GPU -- it's just slower for large-scale simulations. GPU presets require GPU quota which new Azure subscriptions don't have by default.

When to Use Which

Project Structure

one-click-mujoco-azure/
├── pyproject.toml              # Package config, "simup" CLI entry point
├── simup/                      # The CLI package (this is what `pip install -e .` installs)
│   ├── cli.py                  # All user-facing commands (Click + Rich)
│   ├── config.py               # Config loading (~/.simup/), presets, env vars
│   ├── azure_vm.py             # Azure SDK calls: create/get/list/delete VMs
│   └── startup_script.sh       # Cloud-init script that runs on first VM boot
├── robot/                      # Simulation code (deployed to the VM)
│   ├── simulate.py             # Headless humanoid sim + video rendering
│   └── humanoid_demo.ipynb     # Interactive Jupyter demo
├── examples/                   # Benchmarks and demos (deployed to the VM)
│   ├── humanoid_walk.py        # CPU vs GPU benchmark
│   └── batched_humanoid_mjx.py # 1024 parallel envs with JAX
├── tests/                      # 70 unit tests (run locally, no Azure needed)
│   ├── test_config.py          # Config loading, env vars, save/load
│   ├── test_azure_vm.py        # Name generation, SSH keys, wait logic
│   ├── test_cli.py             # All CLI commands via CliRunner
│   └── test_helpers.py         # Output parsing helpers
└── .github/workflows/ci.yml   # CI: lint, test, type-check on every PR

How the pieces connect: cli.py is the entry point -- it parses commands, loads config from config.py, and calls azure_vm.py to provision infrastructure. When a VM boots, startup_script.sh installs MuJoCo, JAX, and Jupyter, then deploys the files from robot/ and examples/.

Learning Path

New to robotics simulation? Here's a suggested path after your first deploy:

1. Open the Jupyter notebook -- simup jupyter <name> --open and run humanoid_demo.ipynb
2. Understand the model -- The notebook shows joint counts, actuators, and observation spaces
3. Try other dm_control tasks -- Change humanoid.stand to humanoid.walk or humanoid.run
4. Run the benchmark -- python3 examples/humanoid_walk.py compares CPU vs GPU performance
5. Scale up -- python3 examples/batched_humanoid_mjx.py runs 1024 parallel environments via JAX
6. Bring your own robot -- Replace the model loading in robot/simulate.py with your own MJCF XML (convert from URDF if needed)

Resources:

• MuJoCo Documentation
• dm_control Suite
• MuJoCo MJX (GPU)
• MuJoCo Playground

Requesting GPU Quota

New Azure subscriptions have 0 GPU quota by default. You must request it:

1. Go to Azure Portal > Subscriptions > your subscription
2. Click Usage + quotas in the left sidebar
3. Search for Standard NCASv3_T4 Family (cheapest GPU option)
4. Click the edit icon and request a new limit of 8 (or more)
5. Submit -- approval can be instant or take up to a few business days

While waiting, use simup deploy --preset cpu to get started on a CPU VM. Physics doesn't care what hardware it runs on.

Troubleshooting

License

MIT

Built by Haptic AI. If this saved you a few hours of Azure debugging, we did our job.