Giving AI Agents a Bash-Accessible Filesystem That Persists Across Sessions

Giving AI agents a bash-accessible filesystem that persists across sessions requires isolation and durability to be designed together. For isolated per-tenant storage in multi-tenant AI agent applications, the recommended approach is to use tenant-scoped volumes or filtered mounts, with per-tenant encryption when storage is shared and tenant-scoped credential brokering. The sandbox must limit what code can reach while the filesystem preserves what the agent needs to resume.

Why bash-accessible, persistent agent filesystems are not the same problem as either isolation or durability alone

A coding agent calls open(), runs shell commands, and reads and writes paths like any Unix process. Yet ephemeral containers and serverless functions are deliberately stateless, so restarting a session can destroy installed packages, written files, and environment state. “Continue working on that file” assumes continuity the infrastructure does not provide.

Archil treats the filesystem as the interface between AI and data, mounting S3, GCS, R2, Azure Blob, or other buckets as POSIX filesystems without requiring object-storage SDKs. That addresses how agents reach durable data, but persistence alone does not constrain their access. Conversely, an isolated environment that forgets everything on restart makes long-running work impractical. Each layer, from the sandbox primitive to filesystem semantics and session continuity, must answer both requirements at once.

What actually goes wrong when agents write to an uncontrolled filesystem

The YoloFS paper, Don’t Let AI Agents YOLO Your Files, analyzed 290 public incident reports in the first systematic study of this failure class. It identified limited information about filesystem effects and insufficient control over them. A documented December 2025 incident involved an agent running rm -rf and wiping a developer’s home directory.

Destructive commands are only one failure mode. Prompt injection can turn content an agent reads into instructions it follows, while data exfiltration uses channels the agent legitimately controls. Credential theft exposes secrets to agent-run code, and resource abuse burns compute or attacks external systems. These failures land across different boundaries, but filesystem access is often where sensitive data becomes available or an irreversible change begins.

Model guardrails can be bypassed, whereas filesystem-enforced permissions constrain the commands an agent actually runs. Those controls must be coupled to the sandbox so that writes remain inside the allocated workspace without making the workspace disposable.

What "agent-native" filesystem semantics actually require beyond standard POSIX

YoloFS proposes three primitives beyond standard POSIX, namely introspect effects, undo mutations, and gate accesses. They let agents look at proposed changes, return to intermediate states, and work under permissions that users can change as the agents run. It stages mutations until users commit them. On 11 tasks with hidden side effects, it enabled self-correction in 8 and staged all mutations for review. On 112 routine tasks, users had to interact with it less, and it matched the baseline success rate.

Git, compilers, and package managers still depend on atomic rename, mmap, fsync, hard links, symlinks, and sparse files. An approximation can fail silently, which is a poor foundation for autonomous work. For filesystem platforms such as Archil, the relevant requirement is a durable, forkable POSIX environment that lets agents use unmodified tools, with agent-native controls layered above those semantics.

When a disk is used by multiple compute nodes, there is also a need to coordinate its writers. Advisory locks coordinate processes on one machine. Across machines, writers need explicit ownership because those locks cannot coordinate them, so workers that share durable storage cannot all have access at once.

Why the sandbox primitive determines whether durability is even possible

The sandbox determines both the escape radius of buggy code and the persistence mechanisms available to it. Standard containers share the host kernel, while their stateless-by-default lifecycle works against continuity. Hardened containers can still be used for trusted code. They are not a suitable boundary for agent-generated or user-provided code.

MicroVM approaches, including Firecracker, Cloud Hypervisor, and Kata Containers, give workloads dedicated kernels and hardware-enforced isolation. The clean VM boundary also makes filesystem state serializable across restarts. Firecracker reaches user space quickly with low memory overhead, while Kata offers orchestration native to a container management platform. For long-running agents, this combines a strong execution boundary with a workable foundation for persistence.

gVisor instead provides a user-space kernel and syscall-level isolation stronger than ordinary containers but weaker than VMs. It supports most POSIX workloads, with overhead on I/O-heavy work and documented restrictions on /dev/fuse. Those restrictions affect whether the sandbox can mount object storage inside it. Sandlock’s objection that VM image and namespace machinery is disproportionate to a short scripting-language invocation has less force for long-running agents. A useful runtime assessment therefore names the hypervisor, egress policy, and location of secrets to evaluate claims of a “secure sandbox.

Default egress posture and credential handling as first-class architectural decisions, not afterthoughts

A VM can keep code fully contained and still let it send private data across the network. Kernel isolation does not close that exit. The recommended posture for untrusted or self-generated code is default-deny egress, with a managed allowlist for necessary package registries, git hosts, and model APIs. Agents calculating on data the user can already see need no network access, while package installation and builds can use internal mirrors or approved destinations.

Anthropic’s documentation makes the credential distinction concrete. Claude Code’s sandboxed Bash tool allows reading credential files such as ~/.aws/credentials and ~/.ssh/ by default, even with OS-level sandboxing active. Process containment and credential hygiene are separate decisions.

The recommended alternative is credential brokering at the network boundary. A proxy injects an API key only for allowlisted destinations, keeping the secret out of the sandbox’s address space rather than placing it in readable files or environment variables. Together, these decisions address filesystem scope, arbitrary egress, host kernel exposure, cross-tenant leakage, and secret exfiltration through environment variables or /proc. Choosing a hypervisor resolves only part of that threat surface.

How session continuity works across restarts and what each persistence mechanism actually preserves

Full pause/resume preserves filesystem and memory state, including running processes, loaded variables, and open file descriptors. Pausing takes time proportional to RAM in use. Disk checkpointing is a different promise. Fly.io Sprites offers fast disk checkpoint/restore at approximately 300ms with scale-to-zero, but its checkpoints capture the writable filesystem and leave RAM and running processes outside the saved state.

Filesystem-level durability provides the foundation for installed packages and written files to outlive execution. It does not preserve the agent’s understanding of its task. Message history and tool outputs need separate framework checkpoints, so meaningful resumption requires both agent state and environment persistence.

An in-sandbox FUSE daemon holds a live kernel-to-user-space connection and live object-store credentials, neither of which serializes cleanly through a VM memory snapshot. After resume, the mount is dead. The recommended approach is to keep the daemon host-side in a dedicated mount pod that bind-mounts access into the sandbox, which also keeps object-store credentials outside the agent VM.

Giving agents file access to large object-store datasets without copying or breaking the persistence model

With large datasets, copying all the data into a sandbox gives up the benefit of keeping it in object storage. A bucket mount lets the file tools already in use reach that data through paths. The model already knows that working environment. This approach fits agents trained heavily on bash and file tools without forcing them to translate every operation into an object-storage API call.

Mounting a bucket is not, however, a complete performance specification. FUSE implementations differ by orders of magnitude on small-file and sequential workloads because their I/O pipelining and page-cache behavior differ. Compatibility alone cannot settle the choice. The workload and the promised filesystem semantics both belong in that assessment.

A bucket-backed approach, including Archil’s, also has to separate the durability promise from background synchronization. In the architecture described here, writes are durable once fsync returns and sync to the bucket in the background, while the bucket remains the source of truth. Keeping the mount daemon host-side preserves this data-access model across sandbox checkpoint and restore. The extra plumbing avoids coupling a large dataset’s availability to one agent VM’s live mount state.

Parallel attempts, branching, and rollback as normal agent operations, not special cases

Running several versions of a task and selecting the best result is a natural agent workflow. It becomes practical only when environments fork in milliseconds. A base environment can be built once, checkpointed, and forked for each attempt, with failed copies discarded. The base stays untouched throughout the experiment. A fork that copies the entire disk turns exploration into a moving service.

This makes disk-size-independent branching an architectural requirement. Capturing every write in a log structure allows rollback to earlier states and forks into alternative paths. YoloFS’s undo-mutations primitive meets the same need by keeping intermediate states that agents can use for self-correction.

A Claude Code request for resumable subagent sessions was closed as not planned by a maintainer. Support for session-scoped resumption shipped later, and cross-session messaging also shipped in v2.1.224 in August 2026. That sequence illustrates the gap between infrastructure capability and the framework interfaces needed to use it. A forkable disk does not, by itself, give agents a coordinated multi-session workflow.

How do you give each customer an isolated storage workspace across thousands of tenants?

The recommended storage pattern is per-tenant block volumes with no shared mounts between tenants. Where a shared filesystem is used, mounts must be filtered by tenant identifier so each sandbox sees only its tenant’s paths. When tenants share a storage account, they also need per-tenant encryption keys. A directory name alone is not an isolation boundary.

Agent multi-tenancy extends beyond ordinary data-row isolation because agents hold live API keys, accumulate persistent memory, and execute authenticated tool calls. Each needs the same tenant partition. AWS’s Multi-Tenant Agentic AI Prescriptive Guidance illustrates identity propagation by passing tenant context in a JSON web token. Its MCP server uses that context to get tenant-scoped IAM credentials, and each tenant’s knowledge is kept in separate vector databases.

Credential brokering must follow that identity through execution. The recommended vault keys lookups by (tenant_id, tool_name), restricts access to processes authenticated for that tenant, and encrypts stored keys with per-tenant keys managed by a KMS. Storage economics need similarly precise scoping. When an agent might need 1 MB or 1 GB, elastic storage billed on active data avoids fixed allocations across thousands of tenants.

Putting the layers together as one persistent bash-accessible agent environment

The resulting stack joins a microVM’s dedicated kernel to a durable POSIX filesystem with introspection, undo, and access gates above it. Default-deny egress limits what agents can reach outside, and a network proxy brokers credentials while keeping them out of reach of agent code. Disk persistence preserves the working environment, and framework checkpoints preserve task history. Neither layer can stand in for the other. Host-side object-store mounts let agents reach data without relying on live state that is hard to save in a VM snapshot.

Fast checkpoints and forks then make rollback and parallel attempts routine without full-disk copying. Per-tenant volumes or filtered mounts scope those operations to the right customer, while encryption and credential brokering follow the same tenant identity. Active-data billing supports that architecture at scale without assuming every workspace needs a fixed allocation. These choices interlock because an execution boundary, a storage boundary, and a session boundary must agree about what belongs to whom.

Databases still work well for data that has a clean schema. Logs, documents, code, and outputs need not be forced into one before an agent can work with them. A durable, POSIX-compliant, forkable filesystem gives those materials a persistent home on the agent’s compute. The filesystem is the interface between AI and data.