# MuJoCo and MJX workflow

> Package, run, evaluate, and compare a MuJoCo-family robotics workflow.

Audience: Simulation and learning engineers
Updated: 2026-08-02
Page: /docs/mujoco-mjx

## Choose classic MuJoCo or MJX deliberately

*The same HIM contracts can wrap different execution shapes.*

| Runtime | Good fit | Typical resource |
| --- | --- | --- |
| MuJoCo | Single/few environments, debugging, deterministic evaluation, CPU rendering | CPU standard or modest GPU for policy inference |
| MJX | Large batched JAX rollouts and accelerator training | GPU standard/high-memory depending on batch and model |
| Brax | JAX-native training and fast batched physics where task fidelity fits | GPU standard |

## Run the workflow

**Run your repository**

```bash
# Run the repository's native command locally, or launch bounded SSH compute:
him compute --key ~/.ssh/id_ed25519.pub --profile gpu
# Connect with the returned SSH command and run the project normally.

# Publish the source and real result video afterward:
him upload ./project.zip --video ./result.mp4 --kind both \
  --run-command "./run.sh" --yes --json
```

> **What HIM records:** Each result identifies the package, runtime, configuration, artifacts, and execution source that produced it. Private package metrics are useful evidence, but only challenge-evaluator metrics become official scores.

> **Keep your existing output path:** New integrations should write to HIM_CANDIDATE_OUTPUT, HIM_EVALUATION_OUTPUT, or HIM_MEDIA_OUTPUT. Existing projects that write artifacts/result.json still work: HIM returns the result as the private summary and preserves the artifacts directory as a downloadable package-artifacts.zip.

> **G1 table-tennis example:** The development scene uses the official Unitree 29-DOF G1 model with a fixed pelvis. Builders can iterate quickly in MuJoCo; selected policies move to a separate Isaac validation lane. A fixed-base result does not claim balance, locomotion, or hardware compatibility.

## Declare the native entrypoint

**Relevant .him/him.yaml section**

```yaml
entrypoints:
  - id: evaluate
    purpose: evaluation
    execution_mode: python
    command: [python, -m, my_project.him_evaluate]
    working_directory: .
    runtime_interface_ref: .him/contracts/runtime.json
    resource_class: cpu-standard
    network_policy: none
    secret_refs: []
    timeout_seconds: 1800
compatibility:
  frameworks: [mujoco, jax]
publication:
  visibility: private
```

Keep the project’s native command. The adapter should accept an immutable run spec and attempt-scoped paths, then write trajectory/state and environment evidence. Do not move simulator code into HIM or translate JAX checkpoints to PyTorch.

## Map the simulator boundary

- Robot and model identity: exact MJCF/URDF/assets digest and adapter version.
- Observation names, ordering, shapes, units, rates, frame conventions, and normalization.
- Action names, ordering, units, limits, control mode, decimation, and fallback behavior.
- Seed, reset/initial state, episode horizon, termination, truncation, and intervention semantics.
- Candidate trajectory/state paths, evaluator input/output path, logs, render inputs, and expected media.
- Evaluator digest and metric definitions. Reward logged by training may be useful, but only the isolated evaluator publishes official metrics.

## Connect your simulator safely

1. Package the smallest existing smoke scenario and keep its native command.
2. Declare the robot assets, observations, actions, units, reset behavior, evaluator, and expected outputs.
3. Run him doctor and resolve missing assets, commands, licenses, runtime requirements, or signal mappings.
4. Run one short private scenario, freeze its outputs, evaluate separately, and render only recorded state.
5. Repeat the same seeds and test cancellation, timeout, and failure paths before publishing a result.

## Use MJX rollouts in a training job

**Approved package command shape**

```bash
# Launch bounded SSH compute, then use the repository's native trainer:
him compute --key ~/.ssh/id_ed25519.pub --profile gpu-48gb
# Connect with the returned SSH command. When finished:
him machine stop <machine-id>
```

The package’s train entrypoint owns the JAX/PyTorch loop and checkpoint format. HIM records attempts, runtime limits, checkpoints, resume history, private artifacts, and later evaluation. Hosted execution is available only for runtime profiles that have passed environment and output checks.