Build, certify, and upload

Build produces the concrete manifest. Certification proves that package locally. Upload publishes the same manifest images, and any bundled player files, then runs hosted checks.

Before starting, install the Coworld package, start Docker, and commit the source you intend to publish.

1. Build the package

Run this from the parent of your Coworld project:

uv run coworld build --project path/to/your-coworld --version 0.1.0

The project directory contains compose.yaml and coworld_manifest_template.json. By default, build writes:

path/to/your-coworld/dist/coworld_manifest.json

The command builds or pulls the Compose images, resolves image references, replaces template placeholders, stamps the version, and validates the hydrated manifest. For game-hosted players it also copies each package-relative player file or directory into the output package; no player Compose service is needed.

Build from committed and pushed source when you declare source_url. This lets the build pin public repository paths to a commit that other people can inspect.

2. Run headless episodes

Start with the certification fixture:

uv run coworld run-episode path/to/your-coworld/dist/coworld_manifest.json

Then exercise the default competitive variant and several seeds:

uv run coworld run-episode path/to/your-coworld/dist/coworld_manifest.json \
  --variant <variant-id> --episodes 3

run-episode prints the artifact directory. Inspect its results, replay, and game and player logs.

Confirm that:

• results validate and scores match what happened;
• each expected player ran and acted through its selected runtime;
• no seat spent the episode waiting on timeouts;
• the replay file exists; and
• seeded runs reproduce while unseeded runs vary.

For game-hosted overrides, pass exactly one file/directory path per seat to run-episode; repeat paths explicitly. No overrides means use bundled players. Player --run and --secret-env are unsupported.

3. Check the browser experience

The play command below is for platform-hosted Coworlds. Game-hosted Coworlds reject it; inspect the completed replay through the declared viewer and use game-owned tests for live surfaces and information boundaries.

uv run coworld play path/to/your-coworld/dist/coworld_manifest.json --variant <variant-id>

Open every printed surface. Join and finish through the player client, watch the global view, and inspect the replay.

Verify information boundaries with more than one seat. A correct player view does not prove the spectator or replay view is safe.

4. Run certification

uv run coworld certify path/to/your-coworld/dist/coworld_manifest.json

Certification runs the manifest fixture and records an ordered transcript. It checks the manifest, images, player launch evidence, results, replay output, and implemented supporting-role probes. Game-hosted certification requires a real seat log for every fixture slot and includes player-file bytes in its cache fingerprint.

The command writes an HTML transcript report and opens it by default. It also prints artifact paths and a replay command.

Open the replay and watch it. The automated replay probe checks that data can load; it cannot judge whether the game state, controls, or redaction are correct.

Certification caches the exact successful manifest, certifier code, transcript, and local image identities. Any change to those inputs invalidates the cached proof.

5. Log in and upload

Coworld upload requires a user credential. Clear any active player session, confirm authentication, then upload the certified manifest:

uv run coworld player unset
uv run softmax status
uv run coworld upload-coworld path/to/your-coworld/dist/coworld_manifest.json \
  --wait-certification

See Authentication and identities if the status command is not authenticated.

If the certification inputs are unchanged, upload reuses the local proof. Otherwise, it certifies again before pushing any image archive. Automatic certification removes its temporary episode files on success, failure, or Ctrl+C. To keep logs, replay, and an HTML report for debugging, run coworld certify explicitly. Build outputs and Docker images remain available for reuse. Forced termination, such as kill -9, can leave temporary files behind.

By default, upload waits for hosted smoke episodes using the bundled certification fixture. --wait-certification also waits for the full hosted certification transcript.

The first authenticated upload of a game.name establishes its owner. Later versions of that name must come from the same owner or a Softmax team member.

Understand the hosted result

The new version is visible after upload. It becomes the version resolved by name only after hosted certification and upload smoke both pass.

You can inspect the current result later:

uv run coworld status cow_...

Use the exit code and transcript to decide what failed:

After a retryable external failure, retry the unchanged candidate with coworld retry-certification cow_.... Rebuild and upload a new version when source, images, or the manifest must change.

What upload does not prove

Hosted automation proves the package can execute. It does not prove the competitive variant is balanced, the scores are informative, or the browser replay tells the right story.

Finish with hosted verification.