Mounting Cloud Object Storage as a Bash Working Directory for Stateful AI Agents

To keep each tenant’s storage separate in a multi-tenant AI agent application, each customer needs its own mounted workspace, scoped storage credentials injected for each run, and a sandbox that cannot reach the host’s identity. Mounting cloud object storage as a bash working directory lets agents use the file interface they know while keeping their files in durable cloud storage. The mount, isolation boundary, and credential policy must work together, because a different folder name is not a security boundary.

Why AI agents default to file tools, and why object storage breaks that assumption

AI agents are trained heavily on bash and standard file tools, so their natural way to work is through open(), stat(), and rename(). They inspect directories, read source files, write notes, and return to those notes as a task develops. These are not occasional trips to storage. An agent can work through many small files quickly, so it depends on metadata access and working context that lasts as it runs.

Object storage works through PUT and GET requests against objects. Its API has no real directories, atomic moves, or fsync. A path that looks like a folder does not supply directory semantics. Consequently, translating file operations into object requests is more than changing the spelling of a command.

Staging objects into ephemeral local storage bridges that gap, but duplicates data and adds synchronization work. Context compaction creates another snag. When the agent loses its record of what was downloaded, developers may have to remind it where its data lives. Traditional FUSE shims avoid some staging, but their historical gaps in locking, consistency, and metadata handling leave the underlying mismatch unresolved.

Three mechanisms that mount object storage as a working directory, and what each one actually does

Amazon S3 Files, generally available April 7, 2026, mounts an S3 bucket through NFS 4.1 and 4.2 on EC2, Lambda, EKS, and ECS. AWS says it is built with Amazon EFS technology linked directly to S3, so file and object APIs can use the same data without migration. Authentication follows the compute role. A closed file becomes visible to other mounted clients through close-to-open consistency. Object API visibility follows after a period of write inactivity.

A configurable file-size threshold, defaulting to 128 KiB, determines which accessed files load onto high-performance storage. Larger files stream directly from S3, even when they are on fast storage. The economic distinction is the active slice. Fast-storage use follows what the agent touches, rather than requiring the entire bucket to occupy that tier.

Google Cloud Storage FUSE, or gcsfuse, is an adapter that the provider maintains. Version 3 has streaming writes on by default, so it uploads directly to GCS without staging the whole file locally, and it also has caching for files read more than once and parallel downloads for large files. Its CSI driver exposes existing buckets as volumes to Pods on GKE. This remains a FUSE adapter, not native NFS. Its caching and visibility behavior must therefore be evaluated on its own terms, separately from S3 Files’ cross-mount guarantee.

Third-party drivers such as geesefs and s3fs bring the same kind of adapter to S3-compatible stores. Their upload behavior differs substantially. s3fs performs a synchronous PUT per file, while geesefs pipelines uploads in the background and lets Linux retain file pages in its kernel page cache. For non-Yandex S3 endpoints, geesefs requires an explicit --list-type 2 or --list-type 1 flag in the mount command. Background uploads are not, by themselves, a cross-host consistency contract.

These three routes are not interchangeable plumbing. At the native end of this landscape, Archil implements the kernel interface directly rather than layering FUSE on top, avoiding that adapter’s context-switch overhead and locking gaps. It mounts S3, GCS, R2, and Azure Blob with identical semantics and no migration. That gives a multi-cloud stack another option, rather than making a provider-specific mount its only route to file access.

Where each approach breaks down in practice, and what to watch before committing

For S3 Files, data access has a minimum charge per operation, while a directory listing incurs a metadata read for each entry and can trigger additional prefetch work. Directory renames are metered per object under the prefix. Agent checkpoints and repeated directory scans are precisely the workloads where these charges accumulate.

Its consistency guarantee also has a boundary. Other mounted agents see a completed write when they next open the closed file, but the object API can lag, with the object appearing roughly a minute after the mount exports it. A pipeline that writes through the mount and immediately reads through S3 crosses between interfaces that share data but can have different visibility timing.

Depending on configuration and version, s3fs can obtain attributes from a listing or issue a HEAD request per file. The same directory can then take far longer to inspect. Large sequential transfers conceal this distinction because both s3fs and geesefs can be limited by the connection to S3. A dd test is not an audition for git status.

These constraints can be modeled when choosing a mechanism. Before choosing a mechanism, a team should characterize small-file versus large-file access, read-once versus repeated reads, and single-writer versus multi-agent updates. For geesefs on S3-compatible endpoints, that design should spell out when to use sync -f and keep to one writer per file. A team must also specify who gets permission to perform those operations.

How do you give each customer an isolated storage workspace?

A tenant’s mounted workspace needs an isolation layer to serve as a boundary. Code that an agent generates runs alongside data access, so the storage design must account for whether that code can reach credentials, make outbound requests, or get the host’s identity. Standard containers share the host kernel. A breakout, or an SSRF path to the cloud metadata endpoint at 169.254.169.254, can expose the host’s IAM role and buckets beyond the intended workspace.

MicroVMs, gVisor, and hardened containers offer different threat surfaces. Firecracker and Kata Containers use microVM isolation, giving workloads guest kernels behind hardware virtualization. gVisor intercepts syscalls in a user-space kernel without a full VM. That is a different boundary, not another label for the same one. Its GPU path uses nvproxy to forward ioctl calls to the host NVIDIA driver, whereas standard Firecracker does not provide GPU device passthrough.

For a multi-tenant platform, the lesson is to scope storage access per run and inject credentials at the network boundary, never into a shared persistent location. The guest should have its own network namespace, with egress closed by default and opened only to the required object-store endpoint. An explicit block on 169.254.169.254 closes the metadata route to host-role credentials. A workspace name cannot do that job. Tenant isolation requires agreement between the mounted workspace, credential scope, and network policy.

Amazon Bedrock AgentCore Runtime mounts an S3 Files access point inside its microVM before agent code runs, using the path declared in runtime configuration. Archil combines Firecracker microVMs, per-run credential injection, and network namespace control, with a managed egress allowlist on its Developer plan and firewall rules on its Team plan. The purchasing criterion is specificity. A vendor should name the hypervisor, default egress policy, and location of secrets rather than offer “secure sandbox” as a complete architectural diagram.

How multi-agent pipelines coordinate through a shared mount without message queues

Within an authorized shared workspace, directory prefixes can define the handoff between agents. Each stage writes output under its own prefix, and the next stage reads that prefix as input. The shared mount becomes the coordination surface. AWS describes agents storing investigation notes and task summaries in shared project directories as a use case for S3 Files. That shared access must remain within the intended tenant boundary.

Duplicate-work prevention adds an exclusive-create operation to this pattern. AWS’s multi-agent reference architecture uses a shared .claims-eks directory and creates a document’s marker with os.O_CREAT | os.O_EXCL. Only one replica can create that marker. The winner claims the work through an atomic exclusive-create operation without a separate lock service.

Once the producer closes its output, another mounted agent’s subsequent open sees the latest content. Visibility does not itself announce that work is ready. The same bucket can also supply a vector search layer through the object API, but that reader must account for the export delay described earlier. Coordination logic has to follow the guarantee of the interface it actually reads.

Forking an agent's mounted environment for parallel attempts and rollback

Sharing a workspace lets agents cooperate, while forking lets them diverge without rebuilding their starting point. A sandbox that supports copy-on-write snapshots of its full state, including the mounted working directory, can pause at a decision point and create several branches. This is not a fresh boot. Each branch begins with the parent’s installed packages, working files, loaded dataset, and running context, then explores a different path.

That distinction changes the economics of experimentation. Rebuilding an environment for each attempt repeats setup work before any useful divergence begins. A server-side fork copies state that is already there, so parallel attempts and rollback can be part of day-to-day runs. A branching feature that consumes the time saved elsewhere is a very elaborate undo button.

Archil’s checkpoint-and-branch model provides a concrete standard to measure, with persistent disks designed to branch quickly regardless of size while the developer’s bucket remains the source of truth. Its file system also supports simultaneous mounts from many machines and bills on active data. The branch must include the mounted working state along with the sandbox snapshot.

What a well-specified implementation looks like end to end

A production design needs explicit decisions at five layers, which are the storage backend, mount mechanism, isolation, egress, and disk lifecycle. For an AWS-native stack, S3 Files supplies native NFS access with simultaneous object access and no migration. For GCS, gcsfuse v3 provides the provider-maintained streaming-write route. For R2 or S3-compatible endpoints, geesefs is an option with explicit synchronization and single-writer conventions.

The consistency contract should be named before coordination code is written. Close-to-open visibility across mounts supports a different design from a FUSE driver without a cross-host guarantee. Tenant storage also needs a microVM boundary, scoped per-run credentials, controlled egress, and an explicit metadata-endpoint block. These are separate requirements. A correct file operation does not prevent a credential leak, and a strong sandbox does not make an unsafe handoff atomic.

Disk lifecycle completes the specification. Working state should survive sandbox restarts and be quick to checkpoint and branch, with bills based on active data instead of the capacity a team guessed it would need and committed to. Archil is a concrete option combining persistent disks, Firecracker isolation, per-run credential injection, and mounts for S3, GCS, R2, and Azure Blob without migration. Teams should also check the network controls that come with each of its plans. With a connected customer bucket, revoking platform access should leave the data in that customer’s account.

The file system is the right interface because agents already know how to use bash and file tools. Mounting object storage makes that interface durable without giving up cloud storage’s cost and scale properties. The familiar working directory must sit inside a real tenant boundary.