LazyFork

Fork running containers with 1 MB of overhead.

A fork is an exact copy of a running container mid-execution: same processes, memory and filesystem, continuing from the same instruction. Forks can be forked again.

How it works:

• One CRIU dump of the container, many lazy restores from it.
• A memory page is copied into a fork only when the fork first touches it.
• Untouched memory is shared through the page cache and costs nothing per fork.
• The filesystem is an overlay stack; each fork writes to its own layer.
• No kernel or CRIU patches.

Install

1. Environment macOS: LazyFork runs its daemon in a Linux VM managed by Lima. Linux: a host with CRIU 4.1+, userfaultfd, overlayfs and cgroup v2, for example Ubuntu 26.04.
2. LazyFork

 pip install lazyfork

Example

Start a container that counts, look inside it, fork it, and watch the fork continue the count:

lazyfork daemon start
lazyfork create python:3.12-slim --name counter -- \
    python3 -c 'import itertools, time; [print(i, flush=True) or time.sleep(1) for i in itertools.count()]'
lazyfork attach counter          # a shell inside: try `cat /var/log/lazyfork/output.log`, then `exit`
lazyfork fork counter --name twin
lazyfork attach twin            # twin picks up the count where counter was; Ctrl-C to detach

Fork a 200 MB container 100 times

A container holding a 256 MB heap, forked a hundred times:

lazyfork create python:3.12-slim --name big -- \
    python3 -c 'import itertools, time; heap = bytearray(256 << 20); [print(i, flush=True) or time.sleep(1) for i in itertools.count()]'
lazyfork fork big -n 100
lazyfork list                   # big: 260 MB; each fork: under 2 MB; all hundred together: 176 MB
lazyfork system stats

Only the original image is the full 260MB; forked containers only take ~1.7MB.

id             name   state     parent   depth    pid   procs      memory   image            
 ──────────────────────────────────────────────────────────────────────────────────────────── 
 1bef01acc3f2   big    running   -            0   5424       1    260.6 MB   python:3.12-slim 
 c3e5f821c855   -      running   big          1   7175       1      1.7 MB   python:3.12-slim 
 1fb2162825f9   -      running   big          1   7188       1      1.7 MB   python:3.12-slim 
 a8c319f0ba0c   -      running   big          1   7201       1      1.7 MB   python:3.12-slim 
 dd6c193815e6   -      running   big          1   7214       1      1.7 MB   python:3.12-slim 
 13bf7caf82bb   -      running   big          1   7227       1      1.7 MB   python:3.12-slim 
...

Use

On Linux, run lazyfork daemon run as root. On macOS, the daemon lives in the VM and these commands manage it; everything else runs from the Mac.

lazyfork daemon start           # creates and boots the VM; the first run takes a few minutes
lazyfork daemon status
lazyfork daemon clean           # deletes all stopped containers
lazyfork daemon stop
lazyfork daemon delete          # removes the VM and everything in it

Every container has a generated id, an optional name, and a parent. Commands take a name, an id, or a unique id prefix.

lazyfork create python:3.12-slim --name agent -- python3 -c 'import time; [time.sleep(1) for _ in iter(int, 1)]'
lazyfork fork agent -n 10           # ten running copies of agent, right now; agent keeps running
lazyfork fork agent --name worker   # a named copy
lazyfork fork worker -n 5           # copies of a copy
lazyfork stop agent                 # snapshot and end the process; still forkable, holds no memory
lazyfork delete worker              # its children keep running

lazyfork exec worker -- hostname    # run a command inside
lazyfork shell worker               # interactive shell inside
lazyfork attach worker              # stream its output
lazyfork freeze worker              # pause; thaw resumes

lazyfork list
lazyfork tree
lazyfork stats worker               # memory, page faults, restore timing; --csv for one row

from lazyfork.client import Client

agent = Client().container("agent")
with agent.fork(10) as forks:
    outputs = [f.exec(["hostname"])["stdout"] for f in forks]
    grandchildren = forks[0].fork(3)

Optional runtime hook, for runtimes that want a say in when they are forked:

• Listen on a unix socket inside the container, given with --hook.
• QUIESCE arrives before a snapshot, RESEED <id> after a restore.
• lazyfork/hook.py is a drop-in implementation; examples/agent.py uses it.

Benchmark

Setup:

• python:3.12-slim container running a Python agent with a 128 MB heap.
• Snapshotted once, forked 1 to 100 times, lazily and with a plain CRIU restore.
• Each fork runs 5 seconds, touching a few pages per second, then its cgroup memory is read.
• Lineage rows: forks of forks, nine levels deep.
• VM: 4 vCPU, 8 GiB, Ubuntu 26.04 arm64. Scripts and CSVs in bench/.