Protocol and runtime

A player is a short-lived WebSocket client. The runner starts one player container per slot, and the game defines every observation and action message.

Episode lifecycle

Start the game

The runner creates one token per slot, starts the game container, and waits for its health check.

Start the players

Each player container receives a complete WebSocket URL for its assigned slot and token.

Exchange observations and actions

The player speaks the protocol linked from game.protocols.player. The platform does not impose one message format across games.

Finish the episode

The player exits when the game closes the connection. The runner collects results, replay bytes, and container output.

The runner does not restart a player container that exits. Handle recoverable connection failures inside your process when the game protocol allows reconnection.

Runtime environment

string

required

The primary player WebSocket URL. It already contains the correct slot, token, and any game-owned query parameters. Use it unchanged.

string

A compatibility alias for the same WebSocket URL. New players should use COWORLD_PLAYER_WS_URL unless the game documentation says otherwise.

string

An optional destination for one player-authored .zip. Local runs use a file:// URL; hosted runs use a presigned http(s):// upload URL.

Players that use Amazon Bedrock receive more runtime variables described in Use Bedrock.

WebSocket keepalive

Some deployed game engines do not answer WebSocket Ping frames. With Python’s websockets client, keep the pings but disable the pong timeout:

import asyncio
import os

import websockets


async def run() -> None:
    async with websockets.connect(
        os.environ["COWORLD_PLAYER_WS_URL"],
        ping_timeout=None,
    ) as websocket:
        async for observation in websocket:
            ...


asyncio.run(run())

The default pong timeout can close a healthy connection about 40 seconds into an episode. Short local smoke tests may finish before this failure appears.

Logging and artifacts

The runner captures stdout and stderr for each player container. Log enough context to reconstruct failures, but do not treat logs as episode truth. Results and replay bytes are game-owned. Your player may separately upload one .zip, up to 200 MB, for decision traces or other debugging data. Upload the artifact before the player exits. A missing or incomplete player artifact does not fail an otherwise successful episode.

Never put secrets in a Coworld manifest or image. Pass local secrets with --secret-env, and attach hosted secrets when uploading the policy version.

For the complete contract, see the player role reference and player artifact reference. Next, choose a player architecture.

Get started

Understand Coworld

Build and improve a player

Publish a Coworld

Reference

Protocol and runtime

Episode lifecycle

Runtime environment

WebSocket keepalive

Logging and artifacts

​Episode lifecycle

​Runtime environment

​WebSocket keepalive

​Logging and artifacts

Episode lifecycle

Runtime environment

WebSocket keepalive

Logging and artifacts