Keeping an AI agent’s environment across sandbox restarts takes more than saving a working directory. It requires durable storage that outlives the microVM and isolation strong enough to keep saved state from becoming a security liability. For stateful, long-running agents, a persistent root disk paired with microVM isolation, restricted network access, and external credential brokering makes restarting a continuation.
Why restarting an agent sandbox from scratch is a genuine engineering problem, not just an inconvenience
The agent finishes its npm install and starts editing, but when it restarts, its environment is gone. Now it must clone the repository again, reinstall packages, and warm caches before returning to useful work. Lost intermediate work forces another attempt, wasting model calls and compounding errors. The agent has become very good at its first day on the job.
This comes from a design assumption inherited from stateless serverless compute, where each invocation is independent. Agents instead accumulate state across many tool calls, so their next action depends on what earlier actions left behind. Treating that environment as disposable makes rebuilding a recurring part of the workload.
What an agent's environment actually contains, and which parts are worth persisting
“Environment state” hides several layers with different recovery costs. The package layer includes language runtimes, dependencies, and compiled artifacts, with network-dependent installs making it especially expensive to rebuild. The repository layer holds source trees, local commits, and uncommitted diffs, whose loss can erase the task’s progress. The cache layer includes pip/npm/cargo caches, compiled outputs, and model weights, which are costly but recoverable from upstream. The working file layer contains intermediate outputs, logs, and generated code, where agent-specific value accumulates and is hardest to reconstruct.
Two other layers need different treatment. Credentials, including tokens, keys, and connection strings, belong outside the sandbox and its saved state. Process memory, including running servers and active database connections, is usually tied too closely to one session to be worth saving for use after a restart. The practical boundary is therefore the filesystem.
The four main strategies for keeping environment state across restarts, and what each one actually costs
The first strategy is rebuilding from a Dockerfile or image on every restart. An image bakes in dependencies, and each restart pulls and runs a fresh copy. This keeps the lifecycle simple for short, isolated tasks whose work does not accumulate across sessions. But anything the task needs to install or clone beyond that image has to be rebuilt, and local commits in the ephemeral layer are lost.
The second strategy attaches a persistent volume to a long-lived sandbox. Files on the volume survive restarts, but the sandbox must stay available or the volume must be reattached at startup. That brings reattachment latency and mount configuration into operations. If the sandbox is deleted rather than stopped, saved files may survive while package paths and runtime environment settings do not. This works when the mounted files are the state that matters, but preserving a directory is not necessarily preserving a usable environment.
The third strategy checkpoints state and restores it from a snapshot. A checkpoint can include the filesystem and sometimes memory, making it useful when restoring a known state is preferable to rebuilding. Its costs arrive at both ends, through snapshot latency when saving and restore latency at startup. The bigger the environment, the bigger its snapshots and the longer they take to restore. Snapshot-based resume speeds up a cold start, but saves state only at checkpoints.
The fourth strategy makes the root filesystem itself durable. Installed tools, repositories, caches, and generated files stay in place when the sandbox stops and restarts. The hard part moves into storage engineering, because the disk must be fast enough to serve the root filesystem and durable beyond the microVM lifecycle. For long-running, stateful agents, this is the right default because they can use the work they have built up without setting up the environment again. The other strategies still fit narrower lifecycles, with less infrastructure to build or operate.
Why persistence and isolation must be solved together, and why solving only one creates a new problem
Persistence carries bad state forward just as faithfully as good state. A compromised environment does not become clean merely because its compute restarts. Choosing durable storage therefore also commits the architecture to an isolation model.
Standard containers share the host kernel, so an escape can expose other tenants’ persisted data on the same host. Snyk’s disclosure of CVE-2024-21626 describes a runc escape that gave a process access to the host filesystem. gVisor intercepts syscalls in user space, reducing the kernel attack surface without a full VM, at the cost of some overhead for I/O-heavy workloads. Anthropic says that when Claude runs code inside claude.ai, it does so in a gVisor container on isolated infrastructure.
Firecracker microVMs instead give each workload a dedicated kernel, requiring an attacker to escape both the guest kernel and the hypervisor. If a breakout could expose another tenant’s persisted data, a microVM is the more conservative default. This model fits agents that act on prompts from users, run AI-generated code, or share infrastructure with other tenants. But isolation alone cannot protect a live API key placed inside the guest on purpose, so the architecture also needs runtime policy.
Restricted egress and credential brokering as complements to a persistent sandbox
A persistent environment with unrestricted outbound access is also a persistent route for data exfiltration. An egress allowlist limits the sandbox to named destinations and blocks everything else. For an agent, that allowlist should cover the package registries, git hosts, and model APIs it legitimately needs.
Credential brokering closes the other obvious route. The sandbox holds a placeholder in place of real API keys in guest files or environment variables. A proxy outside the sandbox substitutes the real credential only for allowlisted hosts, so guest code never sees the raw key. This matters especially when files survive across sessions, because a key written once can remain exposed after every restart. Both egress and credential handling are configuration decisions.
What a persistent root disk architecture looks like in practice, and how Archil implements it
The architecture has a hypervisor setup that supports stop/start cycles, storage that makes writes durable at fsync, network policy at the hypervisor boundary, and credentials kept outside the guest. Archil implements it with Firecracker microVMs whose persistent root disks survive stop, start, and pause. Installed packages, cloned repositories, caches, and generated files are present immediately after restart. The durability boundary is the completed fsync call: once it returns, the writes are stored redundantly across multiple availability zones.
On Archil’s Developer plan, sandboxes can reach only an Archil-managed allowlist of package registries, Git hosts, container registries, OS package mirrors, and model APIs, and that list can’t be customized. Team plans and above write their own firewall rules and can use credential brokering to keep live keys out of the guest. On every plan, ports stay private until they are explicitly exposed. Every Archil disk also exposes an S3-compatible API, allowing other parts of the stack to read working files without mounting it. That interface does not support object versioning, Object Lock, or CopyObject, which matters when connecting inspection or archive pipelines.
Forking and branching a persistent environment for parallel agent attempts and safe rollback
Once the environment is durable, cheap branching makes it useful for more than recovery. An agent can try three refactoring strategies in parallel and return the one that passes tests. Each attempt starts from the same environment, and failed attempts can be thrown away without changing the main state. Branching before a risky action also gives the agent a known-good place to return to. Rollback becomes an API operation.
The deciding constraint is how fast the environment’s disk can branch. If copying a 50 GB environment takes minutes, it has to be planned as part of deployment because it is too slow for an agent turn. Checkpointing and branching an Archil disk takes about 90 ms regardless of disk size, which makes branching the file system at turn level practical. That figure is for the disk: forking a whole running sandbox also snapshots its CPU and memory and briefly pauses the source while it does. Keep separate logs for each attempt so one branch’s output doesn’t bleed into another’s.
Giving a persistent agent environment access to large object storage datasets without copying them in
A durable root disk does not remove the cost of copying a large dataset into it. Agents working on object storage would still pay for transfers and need to keep their local copies in sync. Mounting the data as a POSIX filesystem avoids that separate migration project. This complements object storage and databases. Data with a clean schema stays in a database, while unstructured files and large blobs suit the mounted filesystem.
Amazon S3 Files, generally available since April 2026, mounts S3 buckets as shared NFS filesystems on AWS compute resources, with data remaining in S3. Its access points can confine each agent to its own root directory under its own POSIX identity, which means creating and managing an access point per agent. Archil disks mount existing S3, GCS, R2, Azure Blob, or S3-compatible buckets without migration, keeping the bucket as the source of truth. Writes are durable once fsync returns and sync back to the bucket in the background, and revoking access leaves the data in the customer’s account.
The interface matters because models are disproportionately trained on bash and command-line tools. A mounted directory with POSIX semantics lets an agent use familiar tools rather than learn a custom MCP connector for every source. Those semantics include atomic rename, fsync, hard links, and symlinks. Each bespoke connector otherwise consumes context and adds another failure mode.
Designing per-tenant persistent environments in a multi-tenant agent product
Use one sandbox per session, never reuse it across users, and keep persistent disks separate per tenant. MicroVM separation puts a kernel boundary between workloads, while separate disks keep one tenant’s snapshots, forks, and rollbacks from touching another tenant’s storage. Credential brokering must likewise scope each tenant’s secrets to that tenant’s allowlisted destinations. A coding agent’s GitHub token must not become available to a data analysis agent simply because both use shared infrastructure.
With thousands of tenants, fixed allocations waste capacity when tenant 1 needs 1 MB and tenant 1000 needs 1 GB, so storage should be metered on active data. Cache nodes should sit near the tenant’s compute, and data should move across regions only when explicitly configured to do so. Fast forking can initialize each tenant from a common dependency environment, paying setup cost once. MicroVM isolation, persistent disk, egress allowlist, credential brokering, and fast fork compose differently at the per-user scale, but none of the components change.
A decision framework for choosing a persistence strategy given your agent's actual lifecycle
If setup is cheap and tasks are short and isolated, rebuild from an image because simplicity is worth more than the restart cost. If installs and repository clones are expensive and tasks recur, choose a persistent root disk. Snapshot-restore is an intermediate option when that disk model is unavailable.
Next, decide what code the agent is trusted to run. Containers and a persistent volume are a reasonable starting point for code that humans have written and audited. User-prompted or AI-generated code in a multi-tenant context needs a stronger boundary than a shared-kernel container: a microVM, or gVisor where its performance trade-off and threat model fit.
Finally, ask whether the agent needs parallel attempts, branches before risky actions, or rollback. If it does, fork speed is a requirement, and checkpoints that take seconds are too slow for individual agent turns. If it does not, a simpler volume attachment or long-lived sandbox may suffice. For recurring, untrusted, branching workloads, the complete answer is a Firecracker microVM with a persistent root disk, an egress allowlist, external credential brokering, and fast disk branching. Archil’s sandbox documentation is the next step for readers who want to implement this architecture directly.