Repository navigation
Real snapshotting for fork+restore #205
Description
Context
EpisodeService.checkpoint / restore / fork exist today but they
do kill+restart, not real snapshotting:
checkpointrecords the request log offset + copies the agent
workspacerestore/forkstart a fresh runtime with the saved workspace
contents
That works because the cyber pack's HTTP server is essentially
stateless modulo the log + flag arg. Restarting it produces an
equivalent world.
Future packs won't be that lucky:
- Trading sims have order-book state that takes work to get into
- Robotics sims have rigid-body state that you can't recreate
- Containers with running processes (databases, message queues)
can't be cheaply rebuilt
For those, fork should mean actual state snapshot, not "kill and
re-init."
What this issue tracks
Add real snapshotting capability for runtime backings that need it.
Concretely:
- Implement
RuntimeBacking.checkpoint(instance)to capture state
in a wayrestore(checkpoint, ctx)can rebuild from. - Pick a snapshotting tech per backing class:
- Containers: CRIU,
docker commit, overlayfs commit - Subprocess with stateful protocol: pickle the state machine
over an admin socket - Filesystem state: copy or hardlink the data dir
- Containers: CRIU,
The RuntimeBacking protocol already has the hooks
(checkpoint / restore). They're no-ops by default; this issue is
about real implementations.
Why it matters
Without real snapshotting, fork-based counterfactual training is
limited to stateless worlds. As packs ship that need stateful
runtimes (trading, robotics, hybrid sims), fork either has to
flatten back to "rebuild from manifest" (slow, may diverge from
parent) or this issue lands.
Where to start
src/openrange/core/runtime_backing.py— the protocol with
checkpoint/restorealready declared.src/openrange/core/backings.py—HTTPBacking(today's
in-process, kill+restart impl).src/openrange/core/episode.py— theEpisodeService.fork()flow
that callsrestore.- Issue Add a Kind runtime backing (cyber pack) #189 (multi-process backing) — natural place to wire in
multi-process snapshot support.
Suggested phasing
This is research-flavored. No near-term consumer; pick it up when a
pack ships that needs it.
If you want to drive: open a design doc PR with one specific
backing's snapshot strategy + perf budget. Don't try to design "all
snapshotting" at once.
Acceptance
- A
RuntimeBackingimplementation that does real snapshot/restore
for some non-trivial backing (containers + processes inside them
is the canonical hard case). - A test showing
fork()produces a sibling whose state diverges
from the same starting point, not from "manifest re-init."
Notes
Filed for visibility. Don't expect this to land soon unless there's
a forcing function (a stateful pack that needs it).
Activity
[-][roadmap] Container snapshotting for stateful runtimes[/-][+]Add real container / state snapshotting for fork+restore (CRIU / overlayfs / docker commit)[/+][-]Add real container / state snapshotting for fork+restore (CRIU / overlayfs / docker commit)[/-][+]Real snapshotting for fork+restore[/+]larstalian commentedon Oct 12, 2026
No longer involved with this project, so closing my open issues. Feel free to reopen anything you still want to track.