better default config

.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(test:*)",
+      "Bash(cat:*)",
+      "Bash(tree:*)",
+      "Bash(HOME=/tmp/test_home bash -c:*)",
+      "Bash(chmod:*)",
+      "WebSearch"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

CLAUDE.md

@@ -0,0 +1,297 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is a Hugging Face Space that provides a GPU-accelerated JupyterLab environment for training and simulating robots using the MuJoCo physics engine. The space covers a wide range of robotics applications including locomotion, manipulation, motion tracking, and general physics simulation. It is designed to run in a Docker container with NVIDIA GPU support for hardware-accelerated physics rendering.
+
+## What This Environment Supports
+
+This is a general-purpose MuJoCo training environment with sample notebooks covering:
+
+1. **General MuJoCo Physics** (`tutorial.ipynb`) - Comprehensive introduction to MuJoCo fundamentals including basic rendering, simulation loops, contacts, friction, tendons, actuators, sensors, and advanced rendering techniques
+
+2. **Locomotion** (`locomotion.ipynb`) - Training quadrupedal and bipedal robots for walking, running, and acrobatic behaviors. Includes environments for Unitree Go1/G1, Boston Dynamics Spot, Google Barkour, Berkeley Humanoid, Unitree H1, and more
+
+3. **Manipulation** (`manipulation.ipynb`) - Robot arm and dexterous hand control. Includes Franka Emika Panda pick-and-place tasks and Leap Hand dexterous manipulation with asymmetric actor-critic training
+
+4. **Motion Tracking** (`opentrack.ipynb`) - Humanoid motion tracking and retargeting using the OpenTrack system with motion capture data
+
+## Architecture
+
+### Container Environment
+- **Base Image**: nvidia/cuda:12.8.1-devel-ubuntu22.04
+- **Python**: 3.13 (Miniconda)
+- **GPU Rendering**: Uses EGL (OpenGL for headless rendering) with NVIDIA drivers
+- **Web Server**: JupyterLab on port 7860
+
+### Key Components
+
+1. **GPU Initialization** (`init_gpu.py`): Validates GPU setup before starting JupyterLab
+   - Checks NVIDIA driver accessibility via `nvidia-smi`
+   - Verifies EGL library availability (libEGL.so.1, libGL.so.1, libEGL_nvidia.so.0)
+   - Tests EGL device initialization with multiple fallback methods (platform device, default display, surfaceless)
+   - Validates MuJoCo rendering at multiple resolutions (64x64, 240x320, 480x640)
+   - Critical environment variables: `MUJOCO_GL=egl`, `PYOPENGL_PLATFORM=egl`, `EGL_PLATFORM=surfaceless`
+
+2. **MuJoCo Playground Setup** (`init_mujoco.py`): Downloads MuJoCo model assets
+   - Imports `mujoco_playground` which automatically clones the mujoco_menagerie repository
+   - This repository contains robot models (quadrupeds, bipeds, arms, hands, etc.)
+
+3. **Server Startup** (`start_server.sh`): Container entrypoint
+   - Sets up NVIDIA EGL library symlinks at runtime (searches /usr/local/nvidia/lib64, /usr/local/cuda/lib64, /usr/lib/nvidia)
+   - Runs GPU validation (`python init_gpu.py`)
+   - Downloads MuJoCo assets (`python init_mujoco.py`)
+   - Disables JupyterLab announcements
+   - Launches JupyterLab with iframe embedding support for Hugging Face Spaces
+
+### Sample Notebooks
+
+Sample notebooks are organized in individual folders within `samples/` and are automatically copied to `/data/workspaces/` at container startup:
+
+- **`samples/tutorial/`** - Complete MuJoCo introduction (2258 lines) covering physics fundamentals, rendering, contacts, actuators, sensors, tendons, and camera control
+- **`samples/locomotion/`** - Quadrupedal and bipedal locomotion training (1762 lines) with PPO, domain randomization, curriculum learning, and policy fine-tuning
+- **`samples/manipulation/`** - Robot manipulation (649 lines) including pick-and-place (Panda arm) and dexterous manipulation (Leap Hand) with asymmetric actor-critic
+- **`samples/opentrack/`** - Humanoid motion tracking/retargeting (603 lines) including dataset download, training, checkpoint conversion, and video generation
+
+Each sample is copied to its own workspace directory (`/data/workspaces/<sample_name>/`) at runtime. Notebooks are only copied if they don't already exist, preserving any user modifications.
+
+## Development Commands
+
+### Running Locally with Docker
+
+```bash
+# Build the container
+docker build -t mujoco-training .
+
+# Run with GPU support
+docker run --gpus all -p 7860:7860 mujoco-training
+```
+
+### Testing GPU Setup
+
+```bash
+# Validate GPU rendering capabilities (run inside container)
+python init_gpu.py
+
+# Check NVIDIA driver
+nvidia-smi
+
+# Test EGL libraries
+ldconfig -p | grep EGL
+```
+
+### JupyterLab Access
+
+- Default port: 7860
+- Default token: "huggingface" (set via `JUPYTER_TOKEN` environment variable)
+- Default landing page: `/lab/tree/workspaces/locomotion/locomotion.ipynb`
+- Notebook working directory: `/data` (when deployed as Hugging Face Space)
+
+### Persistent Storage and Workspaces
+
+When deployed on Hugging Face Spaces, the `/data` directory is backed by persistent storage. At container startup, `start_server.sh` automatically:
+
+1. Creates `/data/workspaces/` if it doesn't exist
+2. For each sample in `samples/`, creates `/data/workspaces/<sample_name>/` if it doesn't exist
+3. Copies the `.ipynb` file only if it doesn't already exist in the workspace (preserving user modifications)
+4. Copies any additional files from the sample directory (datasets, scripts, etc.)
+
+This ensures:
+- User modifications to notebooks are preserved across container restarts
+- Each sample has its own isolated workspace for generated data, models, and outputs
+- Sample notebooks can include supporting files that are copied to the workspace
+- Users can create additional workspaces in `/data/workspaces/` for their own projects
+
+## Critical EGL Configuration
+
+The container requires specific EGL configuration for headless GPU rendering:
+
+1. **NVIDIA EGL Vendor Config**: Created at `/usr/share/glvnd/egl_vendor.d/10_nvidia.json` pointing to `libEGL_nvidia.so.0`
+2. **Library Path**: `LD_LIBRARY_PATH` includes `/usr/local/nvidia/lib:/usr/local/nvidia/lib64:/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64`
+3. **Runtime Symlinks**: `start_server.sh` creates symlinks to `libEGL_nvidia.so.0` from mounted NVIDIA directories
+4. **Environment Variables**: `__EGL_VENDOR_LIBRARY_DIRS=/usr/share/glvnd/egl_vendor.d`
+
+### Troubleshooting EGL Issues
+
+If MuJoCo rendering fails:
+1. Verify NVIDIA drivers: `nvidia-smi` should show GPU info
+2. Check EGL vendor config: `cat /usr/share/glvnd/egl_vendor.d/10_nvidia.json`
+3. Verify library loading: `ldconfig -p | grep EGL`
+4. Run comprehensive diagnostic: `python init_gpu.py`
+5. Check that `MUJOCO_GL=egl` is set: `echo $MUJOCO_GL`
+
+## Training Workflows
+
+### General MuJoCo Simulation (tutorial.ipynb)
+
+Basic simulation loop:
+```python
+import mujoco
+model = mujoco.MjModel.from_xml_string(xml)
+data = mujoco.MjData(model)
+
+# Simulation loop
+mujoco.mj_resetData(model, data)
+while data.time < duration:
+    mujoco.mj_step(model, data)
+    # Read sensors, apply controls, etc.
+```
+
+Rendering:
+```python
+with mujoco.Renderer(model, height, width) as renderer:
+    mujoco.mj_forward(model, data)
+    renderer.update_scene(data, camera="camera_name")
+    pixels = renderer.render()
+```
+
+### Locomotion Training (locomotion.ipynb)
+
+Typical workflow using Brax + MuJoCo Playground:
+
+1. **Load environment**: `env = registry.load(env_name)`
+2. **Get config**: `env_cfg = registry.get_default_config(env_name)`
+3. **Configure PPO**: `ppo_params = locomotion_params.brax_ppo_config(env_name)`
+4. **Apply domain randomization**: `randomizer = registry.get_domain_randomizer(env_name)`
+5. **Train**: Use `brax.training.agents.ppo.train` with the environment and randomization function
+6. **Save checkpoints**: Policies saved to `checkpoints/{env_name}/{step}/`
+7. **Fine-tune**: Restore from checkpoint and continue training with modified config
+
+Available environments:
+- **Quadrupedal**: Go1JoystickFlatTerrain, Go1JoystickRoughTerrain, Go1Getup, Go1Handstand, Go1Footstand, SpotFlatTerrainJoystick, SpotGetup, SpotJoystickGaitTracking, BarkourJoystick
+- **Bipedal**: BerkeleyHumanoidJoystickFlatTerrain, BerkeleyHumanoidJoystickRoughTerrain, G1JoystickFlatTerrain, G1JoystickRoughTerrain, H1InplaceGaitTracking, H1JoystickGaitTracking, Op3Joystick, T1JoystickFlatTerrain, T1JoystickRoughTerrain
+
+Full list: `registry.locomotion.ALL_ENVS`
+
+Key training techniques:
+- **Domain Randomization**: Randomizes friction, armature, center of mass, link masses for sim-to-real transfer
+- **Energy Penalties**: `energy_termination_threshold`, `reward_config.energy`, `reward_config.dof_acc` to control power consumption and smoothness
+- **Curriculum Learning**: Fine-tune from checkpoints with progressively modified reward configs
+- **Asymmetric Actor-Critic**: Actor receives proprioception, critic receives privileged simulation state
+
+### Manipulation Training (manipulation.ipynb)
+
+Similar to locomotion but focuses on:
+- **Pick-and-place tasks**: PandaPickCubeOrientation (trains in ~3 minutes on RTX 4090)
+- **Dexterous manipulation**: LeapCubeReorient (trains in ~33 minutes on RTX 4090)
+- **Asymmetric observations**: Use `policy_obs_key` and `value_obs_key` in PPO params to train actor on sensor-like data while critic gets privileged state
+
+Available environments: `registry.manipulation.ALL_ENVS`
+
+### Motion Tracking (opentrack.ipynb)
+
+OpenTrack workflow for humanoid motion tracking:
+1. **Clone repository**: `git clone https://github.com/GalaxyGeneralRobotics/OpenTrack.git`
+2. **Download mocap data**: From `huggingface.co/datasets/robfiras/loco-mujoco-datasets` (Lafan1/UnitreeG1)
+3. **Train policy**: `python train_policy.py --exp_name debug --terrain_type flat_terrain`
+4. **Convert checkpoint**: `python brax2torch.py --exp_name <exp_name>` (Brax → PyTorch)
+5. **Generate videos**: `python play_policy.py --exp_name <exp_name> --use_renderer`
+
+## Python Dependencies
+
+Core stack (see `requirements.txt`):
+- **JupyterLab**: 4.4.3 (with tornado 6.2 for compatibility)
+- **JAX**: CUDA 12 support via `jax[cuda12]`
+- **MuJoCo**: 3.3+ with MuJoCo MJX (JAX-based physics)
+- **Brax**: JAX-based RL framework for massively parallel training
+- **MuJoCo Playground**: Collection of robot environments and training utilities
+- **Supporting libraries**: mediapy (video rendering), ipywidgets, nvidia-cusparse-cu12
+
+## File Structure
+
+```
+/
+├── Dockerfile                      # Container with CUDA 12.8 + EGL setup
+├── start_server.sh                 # Container entrypoint
+├── init_gpu.py                     # GPU validation script (comprehensive EGL tests)
+├── init_mujoco.py                  # MuJoCo Playground asset downloader
+├── requirements.txt                # Python dependencies
+├── packages.txt                    # System packages (currently empty)
+├── on_startup.sh                   # Custom startup commands (placeholder)
+├── login.html                      # Custom JupyterLab login page
+└── samples/                        # Example notebooks (organized by topic)
+    ├── tutorial/
+    │   └── tutorial.ipynb          # MuJoCo fundamentals (2258 lines)
+    ├── locomotion/
+    │   └── locomotion.ipynb        # Robot locomotion (1762 lines)
+    ├── manipulation/
+    │   └── manipulation.ipynb      # Robot manipulation (649 lines)
+    └── opentrack/
+        └── opentrack.ipynb         # Motion tracking (603 lines)
+```
+
+When deployed as a Hugging Face Space with persistent storage:
+```
+/data/                              # Persistent storage volume (mounted at runtime)
+└── workspaces/                     # Sample workspaces (created by start_server.sh)
+    ├── tutorial/
+    │   ├── tutorial.ipynb          # Copied from samples/, preserves user edits
+    │   └── ...                     # User-generated data, models, outputs
+    ├── locomotion/
+    │   ├── locomotion.ipynb
+    │   ├── checkpoints/            # Training checkpoints
+    │   └── ...
+    ├── manipulation/
+    │   ├── manipulation.ipynb
+    │   └── ...
+    └── opentrack/
+        ├── opentrack.ipynb
+        ├── datasets/               # Downloaded mocap data
+        ├── models/                 # Trained models
+        └── videos/                 # Generated videos
+```
+
+## Performance Notes
+
+- **Physics simulation**: Can achieve 50,000+ Hz on single GPU with JAX/MJX (much faster than rendering)
+- **Rendering**: Typically 30-60 Hz, much slower than physics
+- **Training times** (on RTX 4090 / L40S):
+  - Simple manipulation: 3 minutes
+  - Quadrupedal joystick: 7 minutes
+  - Bipedal locomotion: 17 minutes
+  - Dexterous manipulation: 33 minutes
+- **Brax parallelization**: Uses thousands of parallel environments for fast training
+- **Checkpointing**: Critical for curriculum learning and fine-tuning
+
+## Common Patterns
+
+### Visualization Options
+
+```python
+scene_option = mujoco.MjvOption()
+scene_option.flags[mujoco.mjtVisFlag.mjVIS_JOINT] = True           # Show joints
+scene_option.flags[mujoco.mjtVisFlag.mjVIS_CONTACTPOINT] = True   # Show contacts
+scene_option.flags[mujoco.mjtVisFlag.mjVIS_CONTACTFORCE] = True   # Show forces
+scene_option.flags[mujoco.mjtVisFlag.mjVIS_TRANSPARENT] = True    # Transparency
+scene_option.flags[mujoco.mjtVisFlag.mjVIS_PERTFORCE] = True      # Show perturbations
+```
+
+### Named Access Pattern
+
+```python
+# Instead of using indices
+model.geom_rgba[geom_id, :]
+
+# Use named access
+model.geom('green_sphere').rgba
+data.geom('box').xpos
+data.joint('swing').qpos
+data.sensor('accelerometer').data
+```
+
+### Rendering Modes
+
+- **RGB rendering**: `renderer.render()` - returns pixels
+- **Depth rendering**: `renderer.enable_depth_rendering()` then `renderer.render()`
+- **Segmentation**: `renderer.enable_segmentation_rendering()` - returns object IDs and types
+
+## Important Notes
+
+- This is designed for Hugging Face Spaces with GPU instances (NVIDIA L40S or similar)
+- All training uses JAX/Brax for massive parallelization across thousands of environments
+- Policies are typically saved using Orbax checkpointing for fine-tuning
+- Domain randomization is critical for sim-to-real transfer
+- The environment supports multiple RL algorithms (PPO, SAC) through Brax
+- Asymmetric actor-critic (different observations for policy and value function) is commonly used

Dockerfile

@@ -167,11 +167,17 @@ RUN --mount=target=requirements.txt,source=requirements.txt \
 # Copy the current directory contents into the container at $HOME/app setting the owner to the user
 COPY --chown=user . $HOME/app
 
+# Set up OpenTrack (clone repo, install dependencies)
+RUN chmod +x $HOME/app/samples/opentrack/setup.sh && \
+    bash $HOME/app/samples/opentrack/setup.sh
+
 RUN chmod +x start_server.sh
 
 COPY --chown=user login.html /home/user/miniconda/lib/python3.13/site-packages/jupyter_server/templates/login.html
 
-COPY --chown=user samples/ /data/samples/
+# Note: samples/ are already copied via "COPY --chown=user . $HOME/app" above
+# They will be copied to /data/workspaces/ at runtime by start_server.sh
+# (We can't copy to /data during build because the volume is only mounted at runtime)
 
 ENV PYTHONUNBUFFERED=1 \
 	GRADIO_ALLOW_FLAGGING=never \
@@ -179,6 +185,8 @@ ENV PYTHONUNBUFFERED=1 \
 	GRADIO_SERVER_NAME=0.0.0.0 \
 	GRADIO_THEME=huggingface \
 	SYSTEM=spaces \
-	SHELL=/bin/bash
+	SHELL=/bin/bash \
+	JUPYTERLAB_WORKSPACES_DIR=/data/.jupyter/workspaces \
+	JUPYTERLAB_SETTINGS_DIR=/data/.jupyter/settings
 
 CMD ["./start_server.sh"]

samples/opentrack/init_opentrack.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# OpenTrack runtime initialization script
+# This script downloads datasets and sets up symlinks at container startup
+
+set -e  # Exit on error
+
+echo "🤖 Initializing OpenTrack workspace..."
+echo "======================================"
+
+# Define paths
+WORKSPACE="/data/workspaces/opentrack"
+DATASETS_DIR="$WORKSPACE/datasets"
+MODELS_DIR="$WORKSPACE/models"
+VIDEOS_DIR="$WORKSPACE/videos"
+OPENTRACK_REPO="$HOME/OpenTrack"
+
+# Create workspace directories if they don't exist
+mkdir -p "$DATASETS_DIR"
+mkdir -p "$MODELS_DIR"
+mkdir -p "$VIDEOS_DIR"
+echo "✓ Workspace directories ready"
+
+# Download mocap datasets if not already present
+MOCAP_DIR="$DATASETS_DIR/lafan1/UnitreeG1"
+mkdir -p "$MOCAP_DIR"
+
+if [ -z "$(ls -A "$MOCAP_DIR" 2>/dev/null)" ]; then
+    echo ""
+    echo "📥 Downloading motion capture datasets..."
+    echo "   This may take a few minutes on first run..."
+
+    # Use Python with huggingface_hub to download
+    python3 << 'EOF'
+import sys
+from pathlib import Path
+
+try:
+    from huggingface_hub import snapshot_download
+
+    datasets_dir = Path("$DATASETS_DIR")
+
+    print("   Downloading from robfiras/loco-mujoco-datasets...")
+    snapshot_path = snapshot_download(
+        repo_id="robfiras/loco-mujoco-datasets",
+        repo_type="dataset",
+        allow_patterns="Lafan1/mocap/UnitreeG1/*.npz",
+        local_dir=str(datasets_dir),
+        local_dir_use_symlinks=False
+    )
+
+    # Count downloaded files
+    mocap_dir = datasets_dir / "lafan1" / "UnitreeG1"
+    npz_files = list(mocap_dir.glob("*.npz"))
+    print(f"   ✓ Downloaded {len(npz_files)} motion capture files")
+
+except ImportError:
+    print("   ⚠️  huggingface_hub not available, skipping dataset download", file=sys.stderr)
+    print("   You can download datasets manually from:", file=sys.stderr)
+    print("   https://huggingface.co/datasets/robfiras/loco-mujoco-datasets", file=sys.stderr)
+except Exception as e:
+    print(f"   ⚠️  Error downloading datasets: {e}", file=sys.stderr)
+    print("   You may need to run: huggingface-cli login", file=sys.stderr)
+EOF
+
+    echo "✓ Dataset download completed"
+else
+    # Count existing files
+    FILE_COUNT=$(find "$MOCAP_DIR" -name "*.npz" | wc -l | tr -d ' ')
+    echo "✓ Found existing mocap datasets ($FILE_COUNT files)"
+fi
+
+# Set up symlinks for OpenTrack
+if [ -d "$OPENTRACK_REPO" ]; then
+    echo ""
+    echo "🔗 Setting up OpenTrack symlinks..."
+
+    # Create symlink from OpenTrack/data/mocap to datasets
+    OPENTRACK_DATA_DIR="$OPENTRACK_REPO/data/mocap"
+    mkdir -p "$(dirname "$OPENTRACK_DATA_DIR")"
+
+    if [ -L "$OPENTRACK_DATA_DIR" ]; then
+        rm "$OPENTRACK_DATA_DIR"
+    elif [ -d "$OPENTRACK_DATA_DIR" ]; then
+        rm -rf "$OPENTRACK_DATA_DIR"
+    fi
+
+    ln -s "$DATASETS_DIR" "$OPENTRACK_DATA_DIR"
+    echo "   ✓ $OPENTRACK_DATA_DIR -> $DATASETS_DIR"
+
+    # Create symlink from OpenTrack/logs to models
+    OPENTRACK_LOGS_DIR="$OPENTRACK_REPO/logs"
+
+    if [ -L "$OPENTRACK_LOGS_DIR" ]; then
+        rm "$OPENTRACK_LOGS_DIR"
+    elif [ -d "$OPENTRACK_LOGS_DIR" ]; then
+        # Move existing logs to MODELS_DIR
+        if [ "$(ls -A "$OPENTRACK_LOGS_DIR" 2>/dev/null)" ]; then
+            echo "   Moving existing logs to $MODELS_DIR..."
+            mv "$OPENTRACK_LOGS_DIR"/* "$MODELS_DIR/" 2>/dev/null || true
+        fi
+        rm -rf "$OPENTRACK_LOGS_DIR"
+    fi
+
+    ln -s "$MODELS_DIR" "$OPENTRACK_LOGS_DIR"
+    echo "   ✓ $OPENTRACK_LOGS_DIR -> $MODELS_DIR"
+else
+    echo "⚠️  OpenTrack repository not found at $OPENTRACK_REPO"
+fi
+
+echo ""
+echo "======================================"
+echo "✅ OpenTrack workspace initialized!"
+echo ""
+echo "   Datasets: $DATASETS_DIR"
+echo "   Models:   $MODELS_DIR"
+echo "   Videos:   $VIDEOS_DIR"
+echo ""

samples/opentrack/opentrack_quickstart.ipynb

@@ -0,0 +1,381 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# OpenTrack Quickstart\n",
+    "\n",
+    "This simplified notebook lets you jump straight into training humanoid motion tracking policies with OpenTrack!\n",
+    "\n",
+    "**Everything is already set up:**\n",
+    "- ✅ OpenTrack repository cloned\n",
+    "- ✅ PyTorch and dependencies installed\n",
+    "- ✅ Motion capture datasets downloaded\n",
+    "- ✅ Workspace directories created\n",
+    "\n",
+    "Just run the cells and enjoy! 🚀"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "First, let's set up our workspace paths and helper functions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import subprocess\n",
+    "import time\n",
+    "from pathlib import Path\n",
+    "from IPython.display import Video, display, HTML\n",
+    "\n",
+    "# Workspace paths (already set up by container initialization)\n",
+    "WORKSPACE = Path(\"/data/workspaces/opentrack\")\n",
+    "DATASETS_DIR = WORKSPACE / \"datasets\"\n",
+    "MODELS_DIR = WORKSPACE / \"models\"\n",
+    "VIDEOS_DIR = WORKSPACE / \"videos\"\n",
+    "OPENTRACK_REPO = Path.home() / \"OpenTrack\"\n",
+    "\n",
+    "# Change to OpenTrack directory\n",
+    "os.chdir(OPENTRACK_REPO)\n",
+    "\n",
+    "print(\"📂 Workspace directories:\")\n",
+    "print(f\"   Datasets: {DATASETS_DIR}\")\n",
+    "print(f\"   Models:   {MODELS_DIR}\")\n",
+    "print(f\"   Videos:   {VIDEOS_DIR}\")\n",
+    "print(f\"\\n✓ Working directory: {os.getcwd()}\")\n",
+    "\n",
+    "# Check if datasets exist\n",
+    "mocap_files = list((DATASETS_DIR / \"lafan1\" / \"UnitreeG1\").glob(\"*.npz\"))\n",
+    "print(f\"\\n✓ Found {len(mocap_files)} motion capture files\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Helper function to run OpenTrack commands\n",
+    "def run_opentrack_command(cmd_args, description=\"Running command\"):\n",
+    "    \"\"\"Run an OpenTrack command and display output\"\"\"\n",
+    "    print(f\"\\n{'='*60}\")\n",
+    "    print(f\"🚀 {description}\")\n",
+    "    print(f\"   Command: python {' '.join(cmd_args)}\")\n",
+    "    print(f\"{'='*60}\\n\")\n",
+    "    \n",
+    "    result = subprocess.run(\n",
+    "        ['python'] + cmd_args,\n",
+    "        capture_output=False,\n",
+    "        text=True\n",
+    "    )\n",
+    "    \n",
+    "    if result.returncode == 0:\n",
+    "        print(f\"\\n✅ {description} completed successfully!\")\n",
+    "    else:\n",
+    "        print(f\"\\n⚠️  {description} exited with code {result.returncode}\")\n",
+    "    \n",
+    "    return result.returncode\n",
+    "\n",
+    "# Helper to find latest experiment\n",
+    "def find_latest_experiment(pattern=''):\n",
+    "    \"\"\"Find the most recent experiment folder\"\"\"\n",
+    "    experiments = [d for d in MODELS_DIR.iterdir() if d.is_dir() and pattern in d.name]\n",
+    "    if not experiments:\n",
+    "        return None\n",
+    "    return sorted(experiments, key=lambda x: x.stat().st_mtime, reverse=True)[0].name\n",
+    "\n",
+    "print(\"✓ Helper functions loaded\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Quick Training (Debug Mode)\n",
+    "\n",
+    "Let's train a quick policy in debug mode to verify everything works. This takes just a few minutes:\n",
+    "\n",
+    "**Parameters:**\n",
+    "- `--exp_name debug` - Name for this experiment\n",
+    "- `--terrain_type flat_terrain` - Train on flat ground"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%time\n",
+    "\n",
+    "run_opentrack_command(\n",
+    "    ['train_policy.py', '--exp_name', 'quickstart_debug', '--terrain_type', 'flat_terrain'],\n",
+    "    description=\"Training OpenTrack policy (debug mode)\"\n",
+    ")\n",
+    "\n",
+    "# Find the experiment\n",
+    "exp_folder = find_latest_experiment('quickstart_debug')\n",
+    "if exp_folder:\n",
+    "    print(f\"\\n📦 Experiment saved: {exp_folder}\")\n",
+    "    print(f\"   Location: {MODELS_DIR / exp_folder}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Convert Checkpoint (Brax → PyTorch)\n",
+    "\n",
+    "OpenTrack trains using Brax (JAX-based), but we need to convert the checkpoint to PyTorch for deployment:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exp_folder = find_latest_experiment('quickstart_debug')\n",
+    "\n",
+    "if exp_folder:\n",
+    "    run_opentrack_command(\n",
+    "        ['brax2torch.py', '--exp_name', exp_folder],\n",
+    "        description=\"Converting Brax checkpoint to PyTorch\"\n",
+    "    )\n",
+    "else:\n",
+    "    print(\"⚠️  No experiment found. Please run training first.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Generate Videos\n",
+    "\n",
+    "Now let's visualize the policy by generating videos using MuJoCo's headless renderer:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exp_folder = find_latest_experiment('quickstart_debug')\n",
+    "\n",
+    "if exp_folder:\n",
+    "    print(f\"🎬 Generating videos for experiment: {exp_folder}\")\n",
+    "    print(f\"   Videos will be saved to: {VIDEOS_DIR}\\n\")\n",
+    "    \n",
+    "    run_opentrack_command(\n",
+    "        ['play_policy.py', '--exp_name', exp_folder, '--use_renderer'],\n",
+    "        description=\"Generating videos with MuJoCo renderer\"\n",
+    "    )\n",
+    "    \n",
+    "    # Give it a moment to finish writing files\n",
+    "    time.sleep(2)\n",
+    "    \n",
+    "    # Find generated videos\n",
+    "    videos = list(VIDEOS_DIR.glob(\"*.mp4\")) + list(VIDEOS_DIR.glob(\"*.gif\"))\n",
+    "    \n",
+    "    if videos:\n",
+    "        print(f\"\\n✅ Generated {len(videos)} video(s):\")\n",
+    "        for v in sorted(videos, key=lambda x: x.stat().st_mtime, reverse=True):\n",
+    "            print(f\"   - {v.name}\")\n",
+    "    else:\n",
+    "        print(\"\\n⚠️  No videos found. They might be in the experiment folder.\")\n",
+    "else:\n",
+    "    print(\"⚠️  No experiment found. Please run training first.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Display Videos\n",
+    "\n",
+    "Let's watch the trained policy in action:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Find all videos\n",
+    "videos = list(VIDEOS_DIR.glob(\"*.mp4\")) + list(VIDEOS_DIR.glob(\"*.gif\"))\n",
+    "videos = sorted(videos, key=lambda x: x.stat().st_mtime, reverse=True)\n",
+    "\n",
+    "if not videos:\n",
+    "    # Search in experiment folders too\n",
+    "    videos = list(MODELS_DIR.glob(\"**/*.mp4\")) + list(MODELS_DIR.glob(\"**/*.gif\"))\n",
+    "    videos = sorted(videos, key=lambda x: x.stat().st_mtime, reverse=True)\n",
+    "\n",
+    "if videos:\n",
+    "    print(f\"🎥 Found {len(videos)} video(s). Displaying...\\n\")\n",
+    "    \n",
+    "    for i, video_path in enumerate(videos[:3]):  # Show up to 3 most recent\n",
+    "        print(f\"\\n{'='*60}\")\n",
+    "        print(f\"Video {i+1}: {video_path.name}\")\n",
+    "        print(f\"{'='*60}\")\n",
+    "        \n",
+    "        try:\n",
+    "            if video_path.suffix == '.mp4':\n",
+    "                display(Video(str(video_path), width=800, embed=True))\n",
+    "            elif video_path.suffix == '.gif':\n",
+    "                display(HTML(f'<img src=\"{video_path}\" width=\"800\">'))\n",
+    "        except Exception as e:\n",
+    "            print(f\"⚠️  Error displaying video: {e}\")\n",
+    "            print(f\"   You can access it at: {video_path}\")\n",
+    "else:\n",
+    "    print(\"⚠️  No videos found.\")\n",
+    "    print(\"\\nMake sure you:\")\n",
+    "    print(\"  1. Trained a policy\")\n",
+    "    print(\"  2. Converted the checkpoint\")\n",
+    "    print(\"  3. Generated videos\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Next Steps\n",
+    "\n",
+    "### Train on Rough Terrain\n",
+    "\n",
+    "Generate terrain and train a more robust policy:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Generate rough terrain\n",
+    "run_opentrack_command(\n",
+    "    ['generate_terrain.py'],\n",
+    "    description=\"Generating rough terrain\"\n",
+    ")\n",
+    "\n",
+    "print(\"\\n✓ Terrain generated!\")\n",
+    "print(\"   You can now train with: --terrain_type rough_terrain\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Train on rough terrain\n",
+    "run_opentrack_command(\n",
+    "    ['train_policy.py', '--exp_name', 'rough_terrain', '--terrain_type', 'rough_terrain'],\n",
+    "    description=\"Training on rough terrain\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Full Training (Longer, Better Results)\n",
+    "\n",
+    "For production-quality results, remove the debug flag and train for longer:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This will take significantly longer but produce better results\n",
+    "# run_opentrack_command(\n",
+    "#     ['train_policy.py', '--exp_name', 'full_training', '--terrain_type', 'flat_terrain'],\n",
+    "#     description=\"Full training (this takes a while!)\"\n",
+    "# )\n",
+    "\n",
+    "print(\"Uncomment the code above to run full training (takes 20-60 minutes on GPU)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Play Reference Motion\n",
+    "\n",
+    "Visualize the original mocap data alongside the policy:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exp_folder = find_latest_experiment()\n",
+    "\n",
+    "if exp_folder:\n",
+    "    run_opentrack_command(\n",
+    "        ['play_policy.py', '--exp_name', exp_folder, '--use_renderer', '--play_ref_motion'],\n",
+    "        description=\"Generating videos with reference motion comparison\"\n",
+    "    )\n",
+    "else:\n",
+    "    print(\"⚠️  No experiment found.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "**What we did:**\n",
+    "1. ✅ Trained a humanoid motion tracking policy using OpenTrack\n",
+    "2. ✅ Converted the checkpoint from Brax to PyTorch\n",
+    "3. ✅ Generated videos of the policy in action\n",
+    "4. ✅ Visualized the results\n",
+    "\n",
+    "**Project Structure:**\n",
+    "```\n",
+    "/data/workspaces/opentrack/\n",
+    "├── datasets/          # Motion capture data\n",
+    "│   └── lafan1/UnitreeG1/*.npz\n",
+    "├── models/            # Trained checkpoints\n",
+    "│   └── <timestamp>_<exp_name>/\n",
+    "└── videos/            # Generated videos\n",
+    "    └── *.mp4, *.gif\n",
+    "```\n",
+    "\n",
+    "**All data persists** across container restarts, so you can continue training or generate new videos anytime!\n",
+    "\n",
+    "For more advanced usage, check out the full `opentrack.ipynb` notebook."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.13.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

samples/opentrack/setup.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# OpenTrack build-time setup script
+# This script clones OpenTrack and installs its dependencies at Docker build time
+
+set -e  # Exit on error
+
+echo "🤖 Setting up OpenTrack at build time..."
+echo "=========================================="
+
+# Clone OpenTrack repository
+OPENTRACK_DIR="$HOME/OpenTrack"
+if [ ! -d "$OPENTRACK_DIR" ]; then
+    echo "📦 Cloning OpenTrack repository..."
+    git clone https://github.com/GalaxyGeneralRobotics/OpenTrack.git "$OPENTRACK_DIR"
+    echo "✓ Repository cloned to $OPENTRACK_DIR"
+else
+    echo "✓ OpenTrack repository already exists"
+fi
+
+# Install PyTorch (CPU version for compatibility)
+echo ""
+echo "🔥 Installing PyTorch..."
+pip install --no-cache-dir \
+    torch==2.5.1 \
+    torchvision==0.20.1 \
+    torchaudio==2.5.1 \
+    --index-url https://download.pytorch.org/whl/cpu
+echo "✓ PyTorch installed"
+
+# Install OpenTrack requirements
+echo ""
+echo "📋 Installing OpenTrack requirements..."
+if [ -f "$OPENTRACK_DIR/requirements.txt" ]; then
+    pip install --no-cache-dir -r "$OPENTRACK_DIR/requirements.txt"
+    echo "✓ OpenTrack requirements installed"
+else
+    echo "⚠️  Warning: requirements.txt not found in OpenTrack repo"
+fi
+
+# Install additional packages for video handling
+echo ""
+echo "🎬 Installing video handling packages..."
+pip install --no-cache-dir imageio imageio-ffmpeg
+echo "✓ Video packages installed"
+
+echo ""
+echo "=========================================="
+echo "✅ OpenTrack build-time setup complete!"
+echo ""

start_server.sh

@@ -19,6 +19,68 @@ python init_gpu.py
 # this will download stuff used by Mujoco (the collection of models)
 python init_mujoco.py
 
+# Copy sample notebooks to persistent storage
+echo "📚 Setting up sample workspaces in /data/workspaces..."
+
+# Create the workspaces directory if it doesn't exist
+mkdir -p /data/workspaces
+
+# Create JupyterLab workspace state directory (for UI preferences, layout, etc.)
+mkdir -p /data/.jupyter/workspaces
+mkdir -p /data/.jupyter/settings
+echo "✓ JupyterLab workspace state directory: /data/.jupyter/workspaces"
+echo "✓ JupyterLab settings directory: /data/.jupyter/settings"
+
+# Loop through each sample directory
+for sample_dir in $HOME/app/samples/*/; do
+    # Get the sample name (e.g., "locomotion" from "samples/locomotion/")
+    sample_name=$(basename "$sample_dir")
+
+    # Create the workspace directory if it doesn't exist
+    workspace_dir="/data/workspaces/$sample_name"
+    if [ ! -d "$workspace_dir" ]; then
+        echo "  Creating workspace: $workspace_dir"
+        mkdir -p "$workspace_dir"
+    else
+        echo "  Workspace already exists: $workspace_dir"
+    fi
+
+    # Copy the .ipynb file only if it doesn't already exist (to preserve user changes)
+    ipynb_file="$sample_dir$sample_name.ipynb"
+    dest_ipynb="$workspace_dir/$sample_name.ipynb"
+
+    if [ -f "$ipynb_file" ]; then
+        if [ ! -f "$dest_ipynb" ]; then
+            echo "  Copying: $sample_name.ipynb → $workspace_dir/"
+            cp "$ipynb_file" "$dest_ipynb"
+        else
+            echo "  Preserving existing: $dest_ipynb (user may have made changes)"
+        fi
+    fi
+
+    # Copy any other files from the sample directory (excluding .ipynb files)
+    # This allows samples to include datasets, scripts, etc.
+    for file in "$sample_dir"*; do
+        filename=$(basename "$file")
+        # Skip if it's the .ipynb file (already handled) or if it's a directory
+        if [ "$filename" != "$sample_name.ipynb" ] && [ -f "$file" ]; then
+            dest_file="$workspace_dir/$filename"
+            if [ ! -f "$dest_file" ]; then
+                echo "  Copying additional file: $filename → $workspace_dir/"
+                cp "$file" "$dest_file"
+            fi
+        fi
+    done
+done
+
+echo "✅ Sample workspaces ready!"
+echo ""
+
+# Initialize OpenTrack (download datasets, create symlinks)
+if [ -f "$HOME/app/samples/opentrack/init_opentrack.sh" ]; then
+    bash "$HOME/app/samples/opentrack/init_opentrack.sh"
+fi
+
 jupyter labextension disable "@jupyterlab/apputils-extension:announcements"
 
 jupyter-lab \
@@ -33,4 +95,4 @@ jupyter-lab \
     --LabApp.news_url=None \
     --LabApp.check_for_updates_class="jupyterlab.NeverCheckForUpdate" \
     --notebook-dir=$NOTEBOOK_DIR \
-    --ServerApp.default_url="/lab/tree/samples/locomotion.ipynb"
+    --ServerApp.default_url="/data/workspaces/opentrack/opentrack_quickstart.ipynb"