Multi-User Gymnasium (MUG)

Multi-User Gymnasium (MUG) converts Gymnasium and PettingZoo environments into browser-based, multi-user experiments. It enables Python simulation environments to be accessed online, allowing humans to interact with them individually or alongside AI agents and other participants.

What does MUG offer?

• Same environment, training to deployment. Run user experiments in the browser against the exact same simulation environments you use to train your AI agents without any rewrites or ports.
• In-browser execution. Python environments and AI policies can run client-side for zero-latency experiences for participants. Heavier environments---or those that can't be compiled to run in the browser---can be run on the server.
• Multi-human Experiments. Built-in networking, rollback netcode, and waiting rooms for multi-participant experiments.
• Experiment orchestration. Scene flow, participant management, and data collection out of the box.
• Extensive customizability. Advanced hooks and configuration for custom rendering, matchmaking, scene logic, and more.

Get started by reading the documentation.

Installation

pip install multi-user-gymnasium[server]

Development

MUG uses uv for package management. From a cloned repository:

# Create the environment and install all dependencies (server, test, docs)
uv sync --all-extras

# Run the unit tests
uv run pytest tests/unit

# Run an example
uv run python -m examples.slime_volleyball.slimevb_human_ai

Dependencies are locked in uv.lock; after changing dependencies in pyproject.toml, run uv lock and commit the updated lockfile.

Releasing

Bump version in pyproject.toml, then build and publish with uv:

uv build
uv publish  # reads UV_PUBLISH_TOKEN or prompts for PyPI credentials

Citation

If you use MUG in your research, please cite:

@article{mcdonald2026cogrid,
  title={CoGrid \& the Multi-User Gymnasium: A Framework for Multi-Agent Experimentation},
  author={McDonald, Chase and Gonzalez, Cleotilde},
  journal={arXiv preprint arXiv:2604.15044},
  year={2026}
}

MUG in the Wild

Below are a list of projects that have used MUG. If you use it in your research, please let us know or open a PR for it to be added here.

@article{mcdonald2025controllable,
  title={Controllable Complementarity: Subjective Preferences in Human-AI Collaboration},
  author={McDonald, Chase and Gonzalez, Cleotilde},
  journal={arXiv preprint arXiv:2503.05455},
  year={2025}
}

Acknowledgements

• This project was originally inspired by the work by Carroll et al. in their Overcooked-AI demo. Most notably in the use of their Overcooked environment and assets in our examples, as well as the use of Phaser (with their client-server implementation).