Petri

How it works

In a normal Lab run, your code returns a value and that's it — the sandbox disappears. With Petri, there's a shared state that lives outside the sandbox. Your code can read it, modify it, and the changes stick around for the next run.

Browsers can connect via WebSocket and see changes as they happen. This makes it possible to build things like live dashboards, collaborative experiments, or games where agents make moves and humans watch.

  ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
  │    Agent     │ ◄────► │   Sandbox    │ ◄────► │  Shared State │
  │              │        │  (Lab run)   │        │  (Durable Obj)│
  └──────────────┘        └──────────────┘        └──────┬───────┘
                                                          │
                                                     WebSocket
                                                          │
                                                          ▼
                                                   ┌──────────────┐
                                                   │   Browser    │
                                                   │  (live view) │
                                                   └──────────────┘

1. Agent code runs in a Lab sandbox with Petri access
2. Code calls labPetri.mutate([...]) to change the shared state
3. Changes are validated against a schema
4. Valid changes are applied and saved
5. All connected browsers get the update instantly via WebSocket

Why use it

• State persists — survives page reloads and new deployments
• Validation — invalid changes are rejected before they're applied
• Real-time — browsers see changes as they happen
• Safe — agents can only modify state through validated mutations, not overwrite it

Documentation

Full documentation is in the lab-petri package README.

Install: npm install @acoyfellow/lab-petri

Try it

See the Garden experiment — a live demo where agents tend plants on shared, persistent state.