Troubleshooting

Runs says the service is offline

Start pnpm research:serve and keep that terminal open. Confirm http://127.0.0.1:9013/health responds, then reopen Runs. Do not bind the service to a LAN address.

Python setup or training fails

Confirm python --version reports 3.12 and uv --version works, then rerun pnpm research:setup. The worker also requires pnpm on PATH. Use pnpm --silent research:worker for direct protocol diagnosis; any non-JSON stdout is a bug.

A run cannot start

Only one job is supported. Stop the active run or wait for it to finish. Inputs outside the supported seed, timestep, and episode-limit bounds are rejected. The service never falls back to an arbitrary command.

A trajectory will not replay

Use a complete schema-1 Runner trajectory. The importer rejects missing headers/end records, incompatible environment versions, malformed JSON, and digest mismatches. An explicitly aborted trajectory remains inspectable but is not evidence of a completed episode.

PPO results differ on another machine

Compare environment version, seed, action sequence, protocol/schema versions, and dependency versions. Identical Runner transition digests are required; identical PPO weights are not guaranteed across hardware or numeric stacks.