Everything below was run for this post on one bare-metal server (384 threads, Ubuntu 26.04), and every output is copied from that run, with noise such as pip's upgrade notice left out. Timings are what the client measured, network and TLS included. They move by tens of milliseconds from one run to the next; an earlier run of the same program forked in 0.23 s instead of the 0.47 s below.

What you need

• A Linux x86_64 machine with systemd and cgroup v2. The project tests on Ubuntu 24.04; this run used 26.04.
• /dev/kvm for Firecracker microVMs, which is what you want for untrusted code. Bare metal works, and so does a cloud VM with nested virtualization. Without KVM the installer sets up containers only.
• Root. The installer sets up system services.
• A few GB of free disk. If you can, put the sandbox state on a local NVMe disk formatted as XFS (more on why in the fork section).

Step 1: install

sudo -i
apt update && apt install -y make git python3-venv
curl -fsSL https://go.dev/dl/go1.27.3.linux-amd64.tar.gz | tar -C /usr/local -xz
git clone https://github.com/kernflux/opendsec && cd opendsec
deploy/quickstart.sh

The script prints what it is doing as it goes:

==> checking this machine
==> building
==> writing the cluster config to /root/opendsec-ops
==> installing (certificates, units, node settings)
==> starting
==> checking the image store
==> importing docker.io/library/python:3.12 as root/py:3.12
==> creating the project root/demo and its caller
==> running a sandbox
  [ok] container sandbox ran python
  [ok] microvm sandbox ran python

OpenDsec is running on this machine.

It took 379 seconds here, most of it compiling. On an 8-core VM expect about 11 minutes.

What you have afterwards is a small but complete cluster, the same components a multi-machine deployment runs, as systemd services:

opendsec-apiserver@0.service  active running
opendsec-e2b@0.service        active running
opendsec-edge.service         active running
opendsec-iam@0.service        active running
opendsec-watcher@0.service    active running

• IAM holds projects, callers and tokens.
• apiserver is the API your code calls. It keeps no state of its own.
• watcher collects each node's capacity for placement.
• edge runs the sandboxes on this machine: Firecracker microVMs and containers.
• e2b serves E2B's API, for code written against E2B's SDK.

The components talk to each other over mutual TLS with a CA the script created. /root/opendsec-ops holds that CA's private key and the admin token, so keep it private. The script also wrote two environment files there:

• env for the admin;
• demo.env for a caller allowed to create sandboxes in the project root/demo.

Step 2: the Python SDK

python3 -m venv .venv && .venv/bin/pip install ./sdk/python
. /root/opendsec-ops/demo.env     # sets OPENDSEC_ADDR, OPENDSEC_TOKEN, OPENDSEC_PROJECT, OPENDSEC_CA

The SDK is async. The rest of this post is one program, shown in pieces, all inside:

import asyncio
from opendsec import DSecClient, DSecRunArgs

async def main():
    async with DSecClient() as client:   # reads the OPENDSEC_* variables
        ...

asyncio.run(main())

Step 3: create a microVM

sb = await client.run_sandbox(DSecRunArgs(
    backend="microvm", image="root/py:3.12",
    cpu_cores_limit=1, memory_limit_mb=1024,
    ttl_running_stop=600,              # stop after 10 idle minutes
    network_rules={"pypi": True}))     # outbound traffic is denied unless a rule allows it
r = await sb.run_shell("python3 -V; uname -r; nproc; free -m | head -2")
print(r.stdout)

[run_sandbox: 0.144s]
Python 3.12.16
6.1.167-opendsec
1
               total        used        free      shared  buff/cache   available
Mem:             985         132         905           0          34         852

0.144 s for the whole call: placement, booting a VM with its own Linux kernel, and the agent inside it answering. Inside, it is the python:3.12 image from Docker Hub with one vCPU and 1 GB, as asked.

Always set backend. The default is sim, which only simulates and runs nothing.

Step 4: files

await sb.write_file("/tmp/hello.py", "import platform\nprint('hello from', platform.node())\n")
print((await sb.run_shell("python3 /tmp/hello.py")).stdout)
print(await sb.read_file("/tmp/hello.py"))

hello from sb-wtm44fgei3hc

There is also list_dir, and run_shell_background for long-running commands.

Step 5: the network is closed by default

The sandbox was created with network_rules={"pypi": True}. So installing from PyPI works:

$ pip install -q requests; python3 -c 'import requests; print(requests.__version__)'
2.34.2

and anything else does not:

$ python3 -c "import requests; requests.get('https://example.com', timeout=5)"
requests.exceptions.ConnectionError: ... Failed to resolve 'example.com' ([Errno -2] Name or service not known)

The policy is enforced on the host with nftables and a DNS proxy. A name the rules do not allow does not resolve, and an address they do not allow is dropped. Rules can name domains, CIDRs and ports, for example {"github.com:443": True}, or {"*": True} to allow everything.

Step 6: pause and resume keep memory

To show that pausing keeps more than files, start a web server inside the sandbox. It lives only in memory:

$ nohup python3 -c "import http.server as h; h.HTTPServer(('127.0.0.1', 8000), h.SimpleHTTPRequestHandler).serve_forever()" >/dev/null 2>&1 &
$ python3 -c "import urllib.request as u; print(u.urlopen('http://127.0.0.1:8000/').status)"
200

Then pause and resume:

await sb.pause()      # [pause: 0.163s]   state PAUSED
await sb.resume()     # [resume: 0.119s]

server still up: 200

Pausing a microVM writes a memory snapshot and ends the VM process, so a paused sandbox holds no RAM. Resuming restores it, and the processes carry on where they were.

Step 7: fork

fork copies a running sandbox, memory included:

forks = await sb.fork(count=3)        # [fork(count=3): 0.465s]

Every copy has the web server already running and the file written earlier:

200
import platform

The copies are independent from then on. A file written in one copy:

$ echo only-in-fork-0 > /tmp/mark        # in forks[0]

is not in the source:

$ cat /tmp/mark                          # in sb
cat: /tmp/mark: No such file or directory

The source is paused for about 10 ms while its state is captured. This is the operation RL rollouts and agent tree search want: bring an environment to an interesting state once, then branch from it several times.

How fast fork is depends on the file system under the sandbox state. Each copy starts from a copy of the memory file. On XFS, as here, that copy is a reflink and costs almost nothing. On ext4 it is a real copy, and forking takes about a second. The installer warns you if the state directory lacks reflink. It uses /data for the state if something is mounted there, so mount an XFS-formatted NVMe disk at /data before installing.

Step 8: a memory snapshot as an image

A snapshot turns the sandbox, memory and all, into an image other sandboxes can start from:

await sb.create_snapshot("root/demo/walk:1", memory=True)    # [create_snapshot: 0.088s]
for i in range(3):
    await client.run_sandbox(DSecRunArgs(backend="microvm", image="root/demo/walk:1",
                                         cpu_cores_limit=1, memory_limit_mb=1024))

[run_sandbox from snapshot #1: 0.045s]
[run_sandbox from snapshot #2: 0.037s]
[run_sandbox from snapshot #3: 0.032s]

A sandbox started from the snapshot already has requests installed and the web server running:

200
2.34.2

This is how you skip setup time. Install the dependencies, load the model, start the services, snapshot once, then start every sandbox from the snapshot, in 32 to 45 ms each here.

Step 9: a container, same API

For trusted work, or where start time and density matter most, use a container. The API stays the same:

c = await client.run_sandbox(DSecRunArgs(backend="container", image="root/py:3.12",
                                         cpu_cores_limit=1, memory_limit_mb=512))

[run_sandbox container: 0.040s]
42
7.0.0-31-generic

The kernel version gives it away. The microVM ran its own 6.1 guest kernel; the container shares the host's 7.0 kernel. That shared kernel is why containers are the faster choice, and why they are the weaker boundary for code you did not write.

Step 10: E2B's SDK

If your agent already uses E2B, the same machine serves E2B's API on port 7400, and demo.env already set E2B_API_URL, E2B_SANDBOX_URL and E2B_API_KEY for it. The key is your OpenDsec token written as e2b_ and hex, because several versions of E2B's Python SDK (2.25 to 2.45) refuse any other form before sending a request. The gateway decodes it back into the token. For a token of your own:

export E2B_API_KEY=e2b_$(printf %s "$OPENDSEC_TOKEN" | od -An -tx1 -v | tr -d ' \n')

Then install the SDK:

.venv/bin/pip install e2b

from e2b import Sandbox

sbx = Sandbox.create()                                   # [Sandbox.create: 0.137s]
print(sbx.commands.run("python3 -c 'print(6*7)'").stdout)   # 42
sbx.files.write("/tmp/a.txt", "hello from e2b")
print(sbx.files.read("/tmp/a.txt"))                      # hello from e2b
sbx.kill()

That is unchanged E2B code. Fork, snapshots and pause with auto-resume work too, and so does the code interpreter once you build its template. The E2B compatibility page lists what does not, such as directory watching and volumes.

Step 11: look at it as the admin

. /root/opendsec-ops/env
opendsecctl status

prints the cluster as the scheduler sees it. For each node it shows whether it is healthy, the backends it offers (microvm, container), its capacity (here 3072 schedulable CPU cores, the 384 threads with the default 8× CPU overcommit; 1.5 TB of memory; up to 1000 microVMs), and what is in use. opendsecctl --help lists the rest: projects and quotas, callers and tokens, images, sandboxes, and pausing a whole task at once.

Cleaning up

Every sandbox above was stopped at the end of the program. They would also have stopped on their own after the 10-minute idle timeout. To remove OpenDsec from the machine:

deploy/quickstart.sh --uninstall

It removes the services, files and network settings it created. A disk mounted for the state through /etc/fstab is emptied but stays mounted.

Where to go from here

• More machines. The single node is a real cluster with one member. The cluster guide adds machines, a shared image store and a load balancer. Upgrades roll through the cluster without stopping running sandboxes.
• No internet. An offline bundle installs the same thing on machines with no internet access.
• Your own images. opendsecctl image import pulls any OCI image. pack_diff (containers) and create_snapshot (microVMs) turn a prepared sandbox into a new one.

OpenDsec is 0.x, AGPL-3.0 for the servers and Apache-2.0 for the SDKs. It is an independent implementation of the design in DeepSeek's DSec paper, not affiliated with DeepSeek. The code is at github.com/Kernflux/opendsec. If something in this walkthrough does not work on your machine, an issue there is the fastest way to get it fixed.

Copying the working directory gives both attempts the same files. It does not give them the same Python heap, running service, or execution position. Replaying the setup might work, but that is a different operation from continuing an existing execution.

This is one of the problems behind OpenDsec, the self-hosted sandbox project I’m building for AI agents and RL rollouts. The useful question is not just “can I snapshot it?” It is “which state does that snapshot actually preserve?”

There are at least three kinds of state

1. Filesystem state

Source code, installed packages, generated files, and local configuration live here. A files-only image is often exactly what you want: build an environment once, then start fresh processes for every attempt.

For an agent that edits a repository and runs tests, this may be sufficient. There is no reason to capture a live process if recreating it is cheap and reliable.

But a saved directory is not a saved interpreter. A variable created in a long-running Python session does not become a file just because the filesystem was copied.

2. Runtime state

This includes process memory and the execution state needed to continue running: loaded data, initialized libraries, in-memory caches, and live local processes.

Suppose a worker has already parsed a large dataset. A filesystem snapshot can preserve the dataset file. A memory-aware snapshot can preserve the worker after parsing it. Those starting points have different costs and different semantics.

That distinction matters when branching an execution. “Start two new environments with these files” is not the same promise as “continue twice from this point.”

3. External state

A remote database, an API request, or a message already sent to another service lives outside the sandbox’s snapshot boundary.

Restoring local memory does not undo a database commit. Forking an agent does not create two independent copies of a payment service. Even if local socket state is captured, the remote peer has not necessarily paused or been cloned with it.

A sandbox snapshot is not a transaction over the outside world. Applications still need reconnect logic, idempotency keys, isolated test services, or explicit checkpoints around external side effects.

How this maps to OpenDsec

OpenDsec has multiple execution backends, and they do not all make the same snapshot promise. According to the current concepts documentation and images and snapshots guide:

• microvm uses Firecracker and supports snapshots and forks with memory. A sandbox created from a memory snapshot resumes with its processes running.
• container supports files-only snapshots and forks. It does not preserve a running Python heap through those operations.
• fullvm uses QEMU, but the current backend capability table does not list fork or snapshot support. Having a VM backend does not automatically mean every lifecycle operation is implemented.

There is also a useful distinction between pack_diff and create_snapshot.

pack_diff builds a reusable image layer from filesystem changes on supported container backends. Think “dependencies installed, repository prepared.” Starting from that image starts fresh processes.

A microVM snapshot with memory is for a different starting point: “the environment is prepared and the processes are already initialized.” The docs expose that choice explicitly:

# Fragment: sb is an existing, initialized microVM sandbox.
# Connection, image import, and sandbox creation are omitted.
img = await sb.create_snapshot("root/rl/warm:v1", memory=True)

This is a documented API fragment, not a benchmark or a complete runnable example. The linked snapshot guide covers setup and creating a sandbox from the saved image.

Where should an agent branch?

Consider a coding agent with this workflow:

1. Prepare a repository and install dependencies.
2. Start a local helper service and initialize a persistent worker.
3. Try one of several candidate patches.
4. Run tests and compare results.

If step 2 is cheap, a files-only image after step 1 may be the simplest choice. Each candidate gets new processes and a clean startup.

If step 2 is expensive, or the worker contains useful state that is awkward to serialize, a memory-aware branch after step 2 becomes worth evaluating.

I would still place the branch before sending writes to shared external services. If each candidate talks to the same mutable database, the experiments are no longer independent just because their local files and memory are isolated.

A useful checkpoint is therefore an application decision, not merely a runtime feature. It should define both what is captured and what each branch is allowed to affect.

What I would test before relying on it

A successful restore is only the first test. For a real agent workload, I would check:

• Memory continuity: does an in-memory value survive without rerunning initialization?
• File continuity: are the expected files present, and do writes in one branch stay out of another?
• Process continuity: is the local service actually ready after restore, rather than merely having a process entry?
• External behavior: what happens to open connections, expired credentials, and requests that were in flight?
• Repeatability: do clocks, random-number state, and concurrent activity affect the comparison between branches?
• Resource use: how much memory and storage do several active branches consume under the actual workload?

These are evaluation questions, not a claim that every application can be resumed transparently. Preserving more state can avoid repeated setup, but it also preserves things you might prefer to reset, including cached credentials or stale connections. Treat memory snapshots as sensitive artifacts, not just convenient images.

Choose the smallest state boundary that works

For short, stateless tasks, a fresh environment is often easier to reason about. For repository edits, a files-only image may be enough. For long-lived workers and branching agent execution, preserving runtime state can make a meaningful difference.

The important part is making that boundary explicit. “Snapshot supported” is too vague unless you know whether it means files, memory, or both—and what remains outside it.

If you want to evaluate this with OpenDsec:

• Start with the English quickstart.
• Read the snapshot semantics and examples.
• Inspect the code or open an issue on GitHub.

The microVM backend requires access to /dev/kvm; a container-only setup will not demonstrate memory-aware snapshots.

For your agent workload, what is hardest to recreate: the files, the live process state, or the external dependencies?

Disclosure: I’m building OpenDsec. This article was prepared with AI assistance and checked against the linked project documentation; it does not report a new benchmark.