Directory Snapshots: Resumable project state for Sandboxes

Sandboxes power everything from background coding agents like Ramp's Inspect to vibe coding platforms like Lovable and reinforcement learning at Meta.

Use cases like these depend on quickly spinning up isolated environments that install dependencies, run code, mutate files, and shut down. State is maintained primarily using the Sandbox filesystem, but when the Sandbox shuts down, that state is lost unless it's explicitly preserved.

Most Sandbox providers offer file system snapshots to address this. However, they have one big limitation: full filesystem snapshots treat the Sandbox state as one atomic unit.

Today we're launching Directory Snapshots in Public Beta. With Directory Snapshots, you can snapshot a specific directory within a running Sandbox and mount it into another Sandbox later, independently of the base image and the rest of the filesystem.

Introducing Directory snapshots

In practice Sandbox state is usually layered into:

• Base OS and system libraries
• Platform dependencies: npm, vite, CLI tools for an agent to use, etc.
• Application code: e.g. a web app generated by an LLM, a cloned git repo for an agent to work on.
• Generated artifacts: generated web page assets, compilation output.

These layers evolve independently. System dependencies receive updates, application code changes frequently, and generated artifacts are often ephemeral. Until now, snapshotting has meant capturing all of them together.

Directory Snapshots allow you to manage these layers independently. Instead of bundling all filesystem state into a single image, you can snapshot and restore just the directory that contains the state you care about.

This fine-grained control over what gets included in a snapshot unlocks powerful new workflows: separating system dependencies from application code, pre-warming Sandboxes to speed up initialization times, and dramatically faster pre-loading of important files.

Separating lifecycle management of system and application state

Most Sandbox filesystems naturally separate into system dependencies and application state. Let’s say for example you’re building a coding agent where the agent uses a sandbox to interact with a user project. The sandbox layout may look like this:

With Directory snapshots, `/project` can evolve independently from the base image.

Here, a Sandbox is restored using a base image that has been updated since the project last ran. The project state is then mounted into the running Sandbox using a previously stored directory snapshot.

This means that security patches, updates to your agent harness, or runtime upgrades no longer require discarding an outdated full filesystem snapshot and rebuilding the sandbox environment from scratch — which can save you many seconds or even minutes of latency.

Pre-warming Sandboxes to speed up startup latency

Another common mechanism for reducing Sandbox startup latency is pre-warming. This means you spin up a Sandbox ahead of time, start any helper processes that need to run inside it, register with external services and health check the Sandbox—all before the sandbox is assigned to a specific project or end-user.

Maintaining a pool of warmed-up Sandboxes allows keeping a fixed number of Sandboxes always ready to go. But since Sandboxes in the pool are identical and you don't know at creation time which project will run in each Sandbox, you can't pre-warm them with any project-specific code. Historically, this meant giving up the ability to use snapshots for application state.

With Directory Snapshots, identical Sandboxes can be created inside the pool, and then project code can be added later, once a sandbox is being claimed from the pool, by mounting a snapshot.

Optimized pre-loading and instant mounting

One advantage of Directory Snapshots is that they integrate directly with Modal’s lazy-loading container filesystem. Modal containers load files on demand, which enables fast startup times even for large images.

For Sandboxes, access patterns differ from typical container workloads. Instead of executing a fixed entry point, users often run different commands, start processes on demand, or iterate on a specific project directory. In these cases, which files are loaded first has a direct impact on perceived startup time.

Directory Snapshots give you control over that behavior. Snapshots are mounted instantly, and their contents are prioritized for pre-loading relative to the rest of the image. By isolating frequently accessed files such as project code, virtual environments, or cached dependencies into a directory snapshot, you can ensure that those files are loaded first, even if the base image is large.

How Directory Snapshots fit into Modal's snapshot ecosystem

Modal now offers three complementary snapshot types, each optimized for different use cases:

• Filesystem Snapshots capture entire Sandbox filesystems. They're implemented as diffs from your base image and persist indefinitely. Perfect for complete environment backups or custom base images.
• Directory Snapshots give you surgical precision. Snapshot specific directories to layer infrastructure, enable warm pool workflows, and speed up initialization. Snapshots persist for 30 days after last use.
• Memory Snapshots capture your Sandbox's memory state for ultra-fast restoration of running processes. Great for long-running experiments or stateful applications.

Together, these three snapshot types give you complete flexibility in managing Sandbox state—from full system images down to individual directories and memory contents.

Check out the full docs for Directory snapshots, and let us know what you think!