Coworld
Coworld is where games become programmable arenas: worlds you can run locally, play in the browser, submit players to, replay, score, and study. A good Coworld gives game authors a complete packaging contract and gives player authors a clear target for building smarter agents.
The coworld package contains the public CLI, Python helpers, manifest types and schemas, runner tooling, and the
Paint Arena reference world.
Start with the Coworld overview for the conceptual map of a complete Coworld.
What Is A Coworld?
A Coworld is a game environment built around a player-improvement loop. It brings together a game, the players that act inside that game, and supporting components that help turn each episode into something useful: results, replays, reports, grader scores, diagnoses, or optimization inputs.
The core loop is simple: run an episode, inspect what happened, improve a player, and run again. The same Coworld can be used for local development and hosted league competition.
Most readers are here to build a player for an existing Coworld. If that is you, start with Developing Players.
If you are building a complete Coworld, start with Developing Coworlds.
Developing Players (Work In Progress)
Most Coworld users are player builders: they want to build an agent for a game that already exists. A player developer chooses a Coworld, learns its rules and player protocol, runs local episodes, inspects the resulting artifacts, improves their policy, and submits it to a league when it is ready.
The player development user guide is still under construction. For now, use:
- Player role for the current player contract.
- Coworld cookbook for current player development recipes.
- Paint Arena as the canonical example world.
- Bedrock for players if your player calls an LLM — how to reach hosted Bedrock through the sidecar endpoint (read this before writing the call; getting it wrong fails silently as a non-LLM baseline).
Developing Coworlds
Coworld builders create the worlds that player developers target. They define the game, the player experience, example or baseline players, local test episodes, local browser-play surfaces, and supporting outputs that help humans and agents understand what happened.
Start with Authoring A Coworld — the end-to-end guide from design through local testing, certification, upload, and hosted verification. It leans on the starter templates and the Paint Arena example as its worked references. Use Rebuilding Coworlds After The Role Repo Move when updating an existing Coworld or fixing a supporting role.
For uploaded games, game.docs.readme should be the durable game-owned guide: rules, strategy, how to use or modify a
game-specific policy, and game-specific FAQs. Shared protocol docs belong in game.protocols; Softmax participation,
policy upload, league submission, standings, logs, and replay instructions belong in the platform play_*.md guide.
The canonical rebuild flow is to copy the relevant template, Paint Arena role, or coworld-tools implementation into
the owning coworld-<slug> repo, then build and publish that game-local source.
Main Workflows
| Workflow | Start with |
|---|---|
| Build or improve a player | Cookbook: Upload And Submit A Player and Player role |
| Call an LLM / Bedrock from a player | Bedrock for players — route through AWS_ENDPOINT_URL_BEDROCK_RUNTIME, InvokeModel not Converse |
| Iterate a player against hosted opponents (XP Requests) | Cookbook: Request Experience Runs and uv run coworld xp-request --help |
| Run local episodes or browser play | Cookbook: Build And Run Paint Arena Locally |
| Test hosted execution against a local Metta platform stack | Cookbook: Certify And Upload A Coworld |
| Inspect league status, logs, results, and replays | Cookbook: Watch Results And Find Episodes |
| Discover reporters and what they produce | uv run coworld reporters list / search <text> / show <rptr_...> (add --json for machine output) |
| Save per-player debugging files after an episode | Player artifact and uv run coworld episode-logs --help |
| Author a new Coworld end to end | Authoring A Coworld |
| Build, certify, and upload a Coworld | Cookbook: Certify And Upload A Coworld |
| Audit Coworld upload workflows | Cookbook: GitHub Upload Workflows and uv run coworld deploy-audit --owner Metta-AI |
| Rebuild an existing Coworld after a role/source move | Rebuilding Coworlds After The Role Repo Move |
| Improve a policy in the optimizer workbench | uv run coworld optimize and Optimizer role |
| Understand package structure and manifest fields | Manifest reference |
What This Package Provides
- CLI workflows for local play, local episode runs, certification, Coworld upload, policy upload/submission, league inspection, and artifact retrieval.
- Pydantic models and generated JSON schemas for Coworld manifests and runner episode requests.
- Local and Kubernetes runner code for executing Coworld episodes.
- Public API client helpers for coding agents that need to inspect leagues, rounds, episodes, replays, and uploaded Coworlds.
- Installable starter templates under
coworld/templatesfor game, player, grader, diagnoser, and optimizer roles. Omit the commissioner template — Softmax leagues use the platform ladder (Commissioner role). (Reporters are submittable wasm components, not containers; see the Reporter role.) - The Paint Arena example, the canonical example for this package's docs.
Coworld does not currently provide a supported hosted game-only lobby where users connect their own remote players. Use
coworld play for local browser play, or submit policies to leagues for fully hosted tournament episodes where the
platform runs the game and every player container.
Documentation Map
The Coworld docs are being reorganized. These links are the current source-of-truth entry points while that work is in progress:
| Need | Current doc |
|---|---|
| Understand what a complete Coworld is | Coworld overview |
| Build and test a new Coworld end to end | Authoring A Coworld |
| Build or operate from recipes | Coworld cookbook |
| Understand manifest fields | Manifest reference |
| Understand roles and artifact flow | Coworld overview |
| Implement a game runnable | Game role |
| Add a browser-only replay viewer | Static replay viewers |
| Implement or submit a player | Player role and Coworld cookbook |
| Call Bedrock / an LLM from a player | Bedrock for players |
| Implement supporting roles | Reporter, Commissioner, Grader, Diagnoser, and Optimizer |
| Create / maintain a platform ladder league | PLATFORM_LADDER_LEAGUE.md |
| Check how ladder seats map to entrants and teams | Platform Ladder Seating |
| Migrate off a container commissioner | MIGRATE_TO_PLATFORM_COMMISSIONER.md |
| Start from installable templates | coworld/templates in the installed package |
| Rebuild with the current role source layout | Rebuilding Coworlds After The Role Repo Move |
| Understand artifact contracts | Artifact reference |
| Consume episode artifacts as a unit | Episode bundle reference |
| Understand the episode lifecycle | Lifecycle overview |
| Debug local or hosted execution | Local runner and Kubernetes runner |
| Start from the canonical example | Paint Arena |
| Look up exact CLI or API reference | uv run coworld --help, uv run coworld <command> --help, and Observatory OpenAPI |
Planned cleanup will shrink or move several of these pages into a smaller set of cookbook, lifecycle, runnable, and artifact documents. Until those pages exist, prefer the links above over older duplicated prose.
Release files for coworld 0.1.40
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| coworld-0.1.40.tar.gz | 2.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| coworld-0.1.40-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / coworld-0.1.40.tar.gz
| Download URL | coworld-0.1.40.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
92cd918a670c9ad5bba19e92eecd142468a11f9b9cb9bd438a24d15797af0fa8
|
|
BLAKE2b-256 checksum How to use checksums |
919e4d0da998d70f028b92d5f023ab5b772e2027757e6c85de58c966da0aaf54
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logRelease files / coworld-0.1.40-py3-none-any.whl
| Download URL | coworld-0.1.40-py3-none-any.whl |
|---|---|
| Size | 360.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d0d7342fa2835084b5971a24a70efa4e7da74f106f08418929d2bee8928dc4e3
|
|
BLAKE2b-256 checksum How to use checksums |
26e21b838be5b539ade2a5e1381537a0b66fab87b2de2fc6d2798788ae956ec9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency log
