Overview
Counterworld documentation.
Counterworld creates running software worlds with shared state, simulated users, history and controllable time.
How the system fits together
A world definition describes the software, its users and the rules that change state. The runtime turns that definition into an isolated world that agents can use through normal interfaces.
DefineSystems, users and rules
RunState, activity and time
MeasureOutcomes and violations
01SystemsStateful APIs and data
02Simulated usersBuyers, customers, admins, employees and operators
03HistoryEvents and prior state
04ClockAdvance or rewind time
Two interfaces: agents use the world's native API, SDK or MCP tools. Test runners use Counterworld to control time, state, checkpoints and forks.
The core model
- World definition
- The reusable schema, mutations, actors and behavior rules.
- World instance
- An isolated running copy with its own state, history and clock.
- Checkpoint
- A named snapshot of the complete world at a specific time.
- Fork
- A new instance that preserves the exact state and history of a checkpoint.
Documentation sections
| Area | Covers |
|---|---|
| Quickstart | Install the SDK, create a world, connect an agent and evaluate a run. |
| Core concepts | The objects and boundaries used across Counterworld. |
| Worlds | Catalog, API-derived and custom world definitions. |
| Runtime | Instances, time, checkpoints, forks and state access. |
| Simulation | Actors, behavior parameters, schedules and interventions. |
| Evaluation | Scenarios, business metrics, invariants and regressions. |
| TypeScript SDK | Client setup, methods, inputs, return types and errors. |
| Interface contracts | Agent, control, inspection, simulation and evaluation boundaries. |
Start at the boundary you own
- Agent engineers: connect an agent to a running world in Runtime.
- Environment builders: model software plus buyer, admin, employee or operator behavior in Worlds and Simulation.
- Evaluation leads: define scenarios and pass criteria in Evaluation.