Mava
A JAX research codebase for rapidly training and evaluating distributed multi-agent reinforcement learning systems.
- Source repo
- instadeepai/Mava
- Stars
- ★ 941
- Last updated
- 1mo ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 41/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A MARL researcher wants to modify
ff_ippo.pydirectly and test a new training idea on JAX accelerators. - Not a fit if
- Teams wanting an importable modular library to reuse
- Users without JAX or GPU/TPU hardware wanting a quick run
- Those needing easy scaling across multiple TPUs/GPUs today
- Source review
- 41/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
Mava is a research-oriented JAX codebase for multi-agent reinforcement learning, built around single-file implementations and rapid iteration. It implements PPO, Q Learning, SAC, MAT, Sable, and GPO systems across independent-learning, centralized-training/decentralized-execution, and heterogeneous-agent paradigms. Training is launched from Python system files, with Hydra configuration supplied from YAML defaults and command-line overrides. Environment wrappers support both JAX and non-JAX environment suites: JAX environments use the Anakin architecture, while non-JAX environments can use Sebulba. Mava natively writes standardized JSON experiment logs for downstream aggregation and plotting with MARL-eval, and it is explicitly not intended as an importable modular library.
A researcher runs a system file such as python mava/systems/ppo/anakin/ff_ippo.py. The system uses Hydra-managed defaults from mava/configs/ and accepts overrides such as env=lbf or env=rware env/scenario=tiny-4ag. It connects environments through wrappers in mava/wrappers/, using Anakin for end-to-end JIT-compiled training with JAX environments or Sebulba for non-JAX environments. Available runnable implementations include ff_ippo.py, ff_mappo.py, rec_qmix.py, ff_isac.py, mat.py, and ff_sable.py. Runs produce standardized JSON logs intended for downstream processing with MARL-eval.
- A MARL researcher wants to modify
ff_ippo.pydirectly and test a new training idea on JAX accelerators. - A researcher training policies in Level-based Foraging needs to launch a PPO system with
env=lbf. - A team studying StarCraft Multi-Agent Challenge, Multi-Robot Warehouse, or Multi-Particle Environments needs existing environment wrappers for repeatable experiments.
- An experimenter comparing discrete-action Q Learning with continuous-action SAC or PPO needs runnable implementations for those algorithm families.
- A research group needs standardized JSON records across MARL runs before aggregating and plotting results with MARL-eval.
How do you install or deploy this agent?
Requires Python 3.11 or 3.12, Git, network access, and JAX dependencies. Clone and install with uv:
git clone https://github.com/instadeepai/Mava.git
cd Mava
uv sync
source .venv/bin/activateFor CUDA 12 use uv sync --extra cuda12; for TPU use uv sync --extra tpu. Alternatively, from a virtual environment run pip install -e ".[cuda12]"; omit [cuda12] without a GPU or on Mac. No API credentials are documented.
How do you use this agent?
For a first run: python mava/systems/ppo/anakin/ff_ippo.py. For Level-based Foraging: python mava/systems/ppo/anakin/ff_ippo.py env=lbf. For the Robot Warehouse tiny-4ag scenario: python mava/systems/ppo/anakin/ff_ippo.py env=rware env/scenario=tiny-4ag. Default system configurations are in mava/configs/. Choose Anakin or Sebulba according to whether the target environment is written in JAX.
What are this agent's strengths and limitations?
- Single-file JAX implementations are designed to be read, changed, and used for rapid MARL research iteration.
- Supports both Podracer architectures: Anakin for JAX environments and Sebulba for non-JAX environments.
- Covers PPO, IQL, QMIX, SAC, MAT, Sable, and GPO, including feed-forward and some recurrent variants.
- Writes standardized JSON logs that connect to MARL-eval aggregation and visualization workflows.
- The project explicitly is not a modular importable library, so adoption generally means working from and modifying repository system files.
- The core runtime depends on JAX, and architecture choice is constrained by whether an environment is written in JAX.
- The algorithm table documents Sebulba support for PPO
ff_ippo.py; the roadmap still lists adding Sebulba versions of more algorithms. - Easy scaling across multiple TPUs/GPUs remains an unchecked roadmap item rather than a documented completed capability.
How does this agent compare with similar options?
Mava says its code philosophy was adapted from PureJaxRL and inspired by CleanRL: all emphasize understandable, research-friendly implementations, while Mava additionally uses small utilities for frequently reused elements such as networks and logging plus Hydra configuration. The README lists JaxMARL as a related project offering accelerated MARL environments with baselines in JAX; Mava focuses on its own training systems and environment wrappers.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mava This agent | 41 · Major gaps | CLIFree | ★ 941 | 1mo ago | Python | — |
| RLinf RL Infrastructure | 35 · Major gaps | Library / SDKFree | ★ 5.6k | today | Python | — |
| AgileRL | 71 · Some gaps | Library / SDKFreemium | ★ 965 | 1d ago | Python | — |
| Relax Omni-Modal RL Engine | 64 · Some gaps | CLIFree | ★ 670 | 1d ago | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows this is a research codebase with no user data collection or external service calls. There are no mechanisms for least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. Therefore all trust criteria score 0.
Self-consistency: README, pyproject.toml, and test files are largely consistent in description and configuration, but no detailed error handling documentation is provided. Dependency availability: Dependencies include multiple GitHub repositories and pinned versions, but no guarantee of dependency availability is provided. Failure messages: No detailed failure message documentation is provided in tests or code.
Audience and scenarios: Clearly aimed at researchers, with multiple algorithms and environments. Capability boundaries: README lists supported algorithms and environments, but does not explicitly state unsupported scenarios. Trigger precision: Provides precise configuration via Hydra configs and command-line overrides. Environment fit: Supports multiple JAX and non-JAX environments, but no detailed adaptation guide is provided.
Information architecture: README is well-structured with installation, quick start, algorithm list, etc. Install notes: Detailed installation steps provided for uv and pip. Naming stability: Algorithm and file naming is consistent. Examples and FAQ: Provides Quickstart notebook and example commands, but lacks FAQ. Known limitations: No explicit list of known limitations. License: Apache-2.0, clear. Versioning and changelog: No changelog provided. Maintenance responsibility: Contribution guide and roadmap exist, but maintainers are not explicitly identified.
Output usability: Provides runnable algorithms and configurations, output is training results. Marginal value: Provides multiple algorithms and environments, valuable for research. Cost-benefit: Installation and usage cost is high, but detailed documentation is provided.
Claim traceability: README cites papers and docs, but not all claims have sources. Cross-source corroboration: Some claims are supported by papers, but no independent verification is provided. Fact-inference separation: README mixes facts and inferences without clear distinction.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- Dependencies include multiple GitHub repositories, which may introduce supply chain risks.
- No changelog is provided, making version updates opaque.
- Known limitations are not explicitly listed, so users may encounter unexpected issues.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
0.1.3 Pre-release
Release notes excerpt
Highlights _This is the last tensorflow system release. After this, tensorflow systems will be deprecated in favour of Jax systems and our new callback redesign_ (https://github.com/instadeepai/Mava/pull/457). Systems - Updates to acme, reverb and tensorflow. - Working centralised and state based architectures. - Recurrent and Multiple Trainer PPO. Environments - What's Changed * Bugfix/ Release aren't triggering pypi push job. by @KaleabTessera in https://github.com/instadeepai/Mava/pull/466 …View on GitHub ↗
FAQ
Can I use Mava as an importable Python MARL library?
Does it require API keys, a model provider, or MCP?
Can it run non-JAX environments?
ff_ippo.py.