Shepherd Forks Agents 5x Faster Than Docker
Shepherd records a running agent as a forkable trace, and its authors report forks 5x faster than Docker.
Shepherd records an agent run as a Git-like trace of typed events, so any past state can be forked and replayed. (Image: MarkTechPost)
Researchers at Northeastern University and Stanford University have released Shepherd, an MIT-licensed Python runtime substrate that writes every agent-environment interaction into a Git-like execution trace. Each interaction behaves like a commit, except the commit covers the agent process and the filesystem together instead of files alone. Replaying a branch reuses over 95% of the prompt cache, because the prefix leading up to the fork point never changed.
Here is the failure it targets. A coding agent reaches step 10 holding edited files, a dev server that is still up, packages it installed along the way, and a warm prompt cache. It then misreads a traceback and rewrites a file that was already correct.
Neither recovery path is cheap. Patching forward keeps every wrong turn inside the context window and grows the token bill with it. Restarting from step one re-pays every model call and every tool call, and it reproduces nothing exactly, because the run was never deterministic to begin with. What an engineer actually wants is to jump back to step eight, and that is the one option mainstream runtimes cannot offer. Git versions files. It has nothing to say about a live process, an open port, or a cache that took twenty minutes to warm up.
What Shepherd Ships
· MIT-licensed and installable with pip install shepherd-ai from PyPI, on Python 3.11 or newer.
· Every agent-environment interaction is stored as a typed event, and the core operations are formalized as functions and mechanized in Lean.
· A commit spans the process and the filesystem copy-on-write, so a branch carries live state rather than a directory snapshot.
· Reported performance: forks 5x faster than Docker, and over 95% prompt-cache reuse on replay.
· Grant enforcement runs at the OS level through Seatbelt on macOS and Landlock on Linux, the latter inside a privileged container.
One caveat belongs up front, and it comes from the team itself: Shepherd is early alpha and is not ready for production. The honest read is that this is a substrate to prototype against and measure, not a dependency to put under a customer-facing agent this month.
The distinction that makes the rest of it work is small and easy to skim past. Most agent tooling treats the transcript as the run. Shepherd treats the transcript as a shadow of the run and records the execution itself as a first-class object, which is why a rewind can restore something a transcript never held.
Four Concepts in the Trace
The documentation organizes the framework around four ideas: tasks, effects, runs, and workspaces. They are worth reading in that order, because each one narrows what the next is allowed to do.
A task is a typed function whose body the model fills in, which makes the signature the contract rather than the prompt. An effect is every crossing of that task boundary, and each crossing can be watched, answered, or refused. A run is the durable record of those crossings, and it is the object a fork is taken from. A workspace is where that run's state lives.
Permissions are declared in the same signature. A binding written as May[GitRepo, ReadOnly] compiles into that run's writable roots and is enforced at the native syscall jail, not by a Python wrapper the model could argue its way around. That placement matters more than it sounds: a guardrail implemented above the interpreter is a guardrail the agent shares a process with.
The signature is the contract. What a run may touch is declared once, compiled, and enforced below the language it is written in.
Formal verification is not decoration here either. Core operations being mechanized in Lean means fork and replay semantics are stated precisely enough to be checked, which is a reasonable thing to want from a layer you intend to trust with rollback.
Running Your First Fork
· Step 1 — Install. Run pip install shepherd-ai on Python 3.11 or newer. Use macOS if you want Seatbelt enforcement, or Linux inside a privileged container for Landlock. Confirm the platform first, because the grant layer is the part that is OS-specific.
· Step 2 — Declare the task, not the prompt. Write the typed signature, then attach permission bindings to it, such as a read-only grant over a Git repo. Anything the signature does not grant is refused at the syscall boundary, so this step is also your blast-radius setting.
· Step 3 — Run, then fork. Let the run record its events, choose the event you want to return to, and fork from there. The branch restores the process and the filesystem together, and because the prompt prefix up to that point is unchanged, replay reuses the cache instead of paying for it twice.
The concepts pages in the repository cover tasks and effects in detail, and the separate experiments repository holds the benchmark harness. Confirm exact call signatures there rather than from any summary, this one included, because an alpha API moves.
What Changes Against Docker?
The short answer is that Docker hands you a filesystem you can rebuild, while Shepherd hands you a moment you can return to. Container snapshots were designed for services that can be restarted cleanly, and a half-finished agent run is the opposite of that.
Capability
Git
Docker
Shepherd
What gets captured
Files in a repository
Container filesystem image
Agent process and filesystem together
Returning mid-run
Files only, live process is gone
Restart from a snapshot
Fork from any recorded event
Fork speed
Not applicable to live state
Baseline in the comparison
5x faster than Docker, as reported
Replay cost
Re-runs every model call
Re-runs every model call
Over 95% prompt-cache reuse
Permission scope
None
Container-level isolation
Per-run writable roots at the syscall jail
Read the last two rows together. Fork speed alone would only be a convenience win, but pairing it with cache reuse changes the economics of an undo: the cheaper it is to go back, the more willing a supervisor is to intervene early instead of letting a bad run finish and hoping to patch it.
Where Meta-Agents Pay Off
Once a run is forkable, something else can sit on top of it and step in before a bad write commits. The team demonstrates three applications, each with a reported number.
Runtime intervention. A live supervisor watching a pair-coding session raised pass rates on CooperBench from 28.8% to 54.7%.
Counterfactual meta-optimization. Branching exploration over candidate strategies beat baselines across four benchmarks by up to 11 points, while cutting wall-clock time by up to 58%.
Tree-RL training. Forking rollouts at selected turns moved TerminalBench-2 from 34.2% to 39.4%.
The pattern repeats across all three. The supervisor is not a stronger model than the agent it watches, it simply has the ability to undo. That is a different lever from the one most agent work pulls, and the CooperBench jump of nearly 26 points is the clearest evidence that the lever is real.
Worth keeping in proportion: these are the authors' own reported figures on their own harness, published alongside the release. Independent replication has not happened yet, and the experiments repository exists precisely so that it can.
Who Should Care
The common trait across the intended users is not the industry. It is long-horizon agent runs against heavy sandbox state, where a failed run is expensive to redo.
· Software engineering and DevOps teams running coding agents that touch real repositories and live services.
· AI infrastructure and agent-platform vendors who need supervision primitives below the framework layer.
· Quantitative finance research, where a rollout carries expensive setup that should never be recomputed from scratch.
· Security tooling and offensive-security research, where isolation and a reliable revert are the baseline requirement.
· Data engineering pipelines where one wrong write costs more than the entire run that produced it.
If your agent finishes in three tool calls and holds nothing but a chat history, none of this buys you anything. The value scales with how much state a run accumulates before it goes wrong.
Your Next Two Moves
First, measure what a failed run currently costs you. Take one long agent task you already run, note the tokens and wall-clock time spent recovering from a mid-run mistake over a week, and you will know within an afternoon whether a 5x fork and 95% cache reuse would pay for the migration. Most teams have never priced this, which is why the restart tax stays invisible.
Second, install it in a throwaway environment and fork one real run. Pick a task with genuine filesystem state, let it fail on purpose, and rewind. Ten minutes of that tells you more than any benchmark table, and early alpha is exactly the stage where filing an issue still shapes the API.
Shepherd makes an agent run into something you can branch, replay, and revert, with the process and the filesystem moving together. The reported gains, 5x faster forks than Docker and over 95% prompt-cache reuse, target the restart tax rather than model capability. It is MIT-licensed, early alpha, and available today for anyone willing to test it honestly.
Which would help your agents more right now, a smarter model or a reliable undo? Tell me in the comments.