Miniverse SDK

miniverse-sdk installs the miniverse command for validating and uploading immutable .mini simulation bundles to Miniverse. It also builds canonical heightfield assets from ordinary 2-D .npy or JSON arrays so the viewer, collision backend, and policy queries share one grid.

Install

uv tool install miniverse-sdk
miniverse agent-help

For a trusted persistent workspace, run:

miniverse auth login

Interactive access and refresh tokens are stored in a user-only file and renewed automatically. On persistent Linux agents, the state is under $XDG_STATE_HOME/miniverse, or ~/.local/state/miniverse.

For CI, remote environments, and ephemeral machines, create a personal token from an authenticated workspace and place its one-time value in the remote secret manager as MINIVERSE_API_TOKEN:

miniverse token create --name "gpu-runner" --json
miniverse token list --json
miniverse token delete TOKEN_ID --json

Heightfield terrain

miniverse terrain build heights.npy environment/terrain.glb \
  --id experiment-001 --cell-size 0.05 0.05 --out-of-bounds clamp --json

Add "environment": {"kind": "glb", "path": "environment/terrain.glb"} to bundle.json, then pack the generated file at that declared path. Run miniverse agent-help terrain for the coordinate-frame, origin, scaling, and policy-query contract.

MuJoCo-only bundles may instead declare an MJCF world entrypoint, for example "environment": {"kind": "mjcf", "path": "environment/world.xml"}. Store its exact local include and STL mesh closure as ordinary files under environment/. Run miniverse agent-help environments for the supported passive-world subset and fail-closed limitations.

Use 512 x 512 or smaller as the portable terrain budget. The CLI warns above that size; the 1,048,576-sample hard limit should be used only after measuring the target browser and simulator profile.

Agent skill

The repository includes a Miniverse skill at skills/miniverse/SKILL.md. Install that skill in your agent, then follow its setup steps. The skill installs or upgrades this package and reads the versioned instructions bundled with the CLI through miniverse agent-help.

Develop

python -m pip install -e .
python -m unittest discover -s tests -v
python -m build
python -m twine check dist/*

Miniverse server-side import remains authoritative. Local validation is preflight feedback for bundle authors and agents.

Approved tests

Run bounded test code against an uploaded immutable revision with miniverse test start ID@REVISION_ID --file test_policy.py --json. The command waits for the retained report by default; use --no-wait, then test status, test results --wait, or test stop to manage the session. See miniverse agent-help tests for the sandbox and canonical frame contract.

License

Apache License 2.0. See LICENSE.