Encrypted Persistent Storage for AI Agents: How Sandbox0 Volumes Store, Snapshot, and Protect Agent State

AI agents need somewhere to put durable state.

Not just conversation memory. Real state.

Code checkout directories. Generated files. Build caches. Model artifacts. Test outputs. Long-running research notes. Intermediate data that one agent produces and another consumes. The longer an agent workflow runs, the more it starts to look like a real workspace instead of a stateless function call.

That is why persistent storage matters for AI agent infrastructure.

But durable workspaces also create a new security surface. If a sandbox volume outlives the sandbox process, then the volume data has to be protected outside the sandbox lifecycle too: in object storage, in snapshots, in restore paths, and in node-local cache files used to make file I/O fast.

Sandbox0 Volumes are designed around that boundary. A sandbox is the execution plane. A Volume is the storage plane. The Volume can survive sandbox deletion, move through snapshot and restore workflows, and be reached through direct file APIs without requiring a running sandbox.

This post explains how that storage system works and how Sandbox0 encrypts persisted S0FS volume data at the application layer.

Why Persistent Agent Storage Needs Its Own Architecture#

The simplest way to persist agent files is to keep the container alive.

That works until it does not.

Containers are runtime objects. They are scheduled, restarted, deleted, evicted, and scaled. A container is a good place to run a process, but it is not a good long-term source of truth for an agent workspace.

Agent storage has different requirements:

• it must survive sandbox deletion and recreation
• it must support normal filesystem reads and writes
• it must be reachable by control-plane workflows, not only by code inside a sandbox
• it must support snapshots, restore, and copy-on-write forks
• it must avoid turning large files into prompt context or ad hoc JSON payloads
• it must protect data after it leaves the sandbox process

Those requirements point to a separate storage layer.

In Sandbox0, a Volume is a persistent storage object that exists independently of any sandbox. A sandbox can mount the Volume and use it like a normal directory. A platform workflow can also address the same Volume by ID through the direct file API. Both paths operate on the same storage namespace.

The important architectural separation is simple:

This separation is what lets an agent runtime be replaceable while its workspace remains durable.

The S0FS Storage Model#

Sandbox0 Volumes are backed by S0FS, a filesystem layer designed for sandbox workloads backed by object storage.

At a high level, S0FS stores a Volume as two kinds of durable objects:

• Manifests, which describe the current filesystem state
• Segments, which store materialized file data

The manifest is metadata-heavy. It records the filesystem tree, file metadata, and references to segment extents. The segment is data-heavy. It stores file payload bytes in object storage so cold files can be loaded on demand.

There is also node-local state used for low-latency mounted workloads:

• a write-ahead log for recent file mutations
• a head state file for the current local view
• snapshot state files for local snapshot operations

That local state is performance-critical. Agent workloads tend to produce many small filesystem operations: write a file, rename it, run a tool, inspect output, update another file. Waiting for every mutation to become a remote object immediately would add avoidable latency.

So S0FS separates the hot path from the durable materialized path:

1. Recent mutations are recorded locally.
2. The current filesystem view remains available to the mounted sandbox.
3. Materialization writes immutable manifest and segment objects to object storage.
4. Later cold reads can fetch only the data range they need.

This gives Sandbox0 a storage layer that behaves like a filesystem to the agent, while still using object storage as the durable backing store.

Why Object Storage Encryption Alone Is Not Enough#

Object storage services often provide server-side encryption. That is useful, but it is not the full boundary Sandbox0 wants for agent workspaces.

S0FS data is not just one opaque uploaded file. It includes manifests, segment objects, local cache files, snapshot state, and restore inputs. Some of those objects live in object storage. Some live briefly or persistently on nodes. Some are read through range requests. Some are used by control-plane workflows that never start a sandbox.

If encryption is only delegated to the object storage provider, then node-local cache files and filesystem-specific object formats are outside the application encryption model.

Sandbox0 encrypts at the S0FS layer instead.

That means S0FS encrypts data before it is written to durable object storage, and encrypts node-local cache state before it is written to disk.

This matters for agent infrastructure because the sensitive data is often not a single user-uploaded secret. It is the workspace itself:

• source code the agent checked out
• generated patches
• customer data used in an analysis task
• temporary credentials written by tools
• logs and intermediate outputs
• artifacts that are later inspected by a human or another agent

Protecting that workspace requires treating Volume storage as part of the security boundary, not just part of the convenience layer.

Application-Layer Encryption in Sandbox0 Volumes#

Sandbox0 Volume encryption is service-side application-layer encryption.

S0FS encrypts persisted volume objects before they are written to object storage. It also encrypts node-local cache files used by the mounted filesystem path, including the S0FS write-ahead log, head state, and snapshot state.

The encryption model follows the object type.

The segment design is important.

Large files should not become all-or-nothing reads. If an agent reads a small byte range from a cold file, S0FS should not need to download and decrypt the entire segment object.

To preserve random reads, S0FS encrypts segment payloads in chunks. Each chunk is independently authenticated, and the manifest records the encryption metadata needed to read the right ciphertext chunk for a requested plaintext byte range.

That gives Sandbox0 both properties:

• persisted segment data is opaque in object storage
• cold file reads can still fetch only the ciphertext chunks needed for the requested range

This is the storage equivalent of keeping the agent API simple without giving up the infrastructure properties underneath.

Snapshots and Forks Stay Inside the Same Storage Boundary#

Persistent agent storage is not only about keeping a directory alive.

Serious agent workflows need recovery and branching.

A snapshot records a point-in-time state of a Volume. A restore moves a Volume back to a known state. A fork creates an independent child Volume that starts from the same data and diverges through copy-on-write behavior.

Those operations are useful because agent work is often speculative:

• snapshot before a risky code migration
• restore after a failed tool run corrupts the workspace
• fork a base repository into multiple independent agent attempts
• compare outputs from several agent branches
• keep a reproducible checkpoint for evaluation runs

S0FS encryption is designed to cover these workflows, not bypass them.

Snapshot state is encrypted locally. Materialized manifest objects are encrypted. Segment objects are encrypted. When a restored or forked Volume reads existing encrypted segments, it uses the metadata recorded in the manifest to decrypt the requested ranges.

The result is a consistent storage boundary across normal writes, cold reads, snapshots, restore paths, and forks.

What This Does and Does Not Protect Against#

It is important to be precise about the security boundary.

Sandbox0 Volume encryption protects persisted S0FS objects and node-local cache files from being stored as plaintext at rest by the storage system.

It does not mean Sandbox0 services are unable to decrypt Volume data.

storage-proxy and ctld hold the configured encryption key because they have to serve normal POSIX filesystem operations. If a sandbox process opens a file, something in the storage layer must decrypt the relevant bytes and return them. The same is true for direct file reads, snapshot restore, and fork workflows.

So this is not end-to-end encryption where only the end user holds a private key and Sandbox0 services cannot decrypt the data.

The model is service-side application-layer encryption:

• object storage does not receive plaintext S0FS objects
• node-local S0FS cache files are not written as plaintext
• storage services can still decrypt data to serve authorized filesystem reads and writes
• team-scoped authorization, sandbox isolation, and network policy remain separate controls

That distinction matters. It keeps the claim useful and accurate.

Why This Matters for AI Agent Platforms#

Agent platforms are moving from stateless tool calls toward durable runtime systems.

That shift changes the infrastructure problem.

Once agents have persistent workspaces, storage becomes part of the runtime contract. It affects latency, cost, recovery, security, and how teams reason about failure.

An agent workspace should not disappear when a sandbox exits. It should not require copying large files through context windows. It should not force every workflow to speak object storage APIs. It should not leave local cache state outside the encryption boundary. And it should not make snapshots and forks a separate storage system.

Sandbox0 Volumes are built around that full set of requirements:

• persistent state independent of sandbox lifetime
• normal filesystem access for agent code
• direct file operations for platform workflows
• snapshots, restore, and copy-on-write forks
• object-storage-backed durability
• application-layer encryption for persisted S0FS objects and local cache state

The short version: a sandbox runs the agent, but the Volume carries the workspace.

For agent systems that need to survive more than one prompt, that distinction becomes the foundation.

FAQ#

Is Sandbox0 Volume encryption end-to-end encryption?

No. It is service-side application-layer encryption. Sandbox0 storage services hold the configured key so they can serve normal filesystem reads, writes, snapshots, restores, and direct file operations. It is not an end-to-end encryption model where Sandbox0 services cannot decrypt Volume data.

Does encryption break random reads from large files?

No. S0FS segment objects are encrypted in independently authenticated chunks. When a cold file read asks for a byte range, S0FS can fetch and decrypt only the ciphertext chunks needed for that range.

Are node-local cache files encrypted too?

Yes. S0FS encrypts local write-ahead log records, head state, and snapshot state before writing them to disk.

Does the agent need to use a special API to benefit from encryption?

No. The agent still sees a normal mounted filesystem path. Encryption happens inside the storage layer.

Can self-hosted deployments control this behavior?

Yes. Self-hosted deployments can control storage-proxy object encryption with services.storageProxy.config.objectEncryptionEnabled, which is enabled by default. The Volume model and public API are documented in the Volume docs. For self-hosted configuration details, see Self-hosted Configuration.

For a broader introduction to persistent Volumes, snapshots, and copy-on-write forks, see Persistent Storage for AI Agent Sandboxes. For storage operations outside a running sandbox, see Direct File Operations for AI Agent Storage.