Bash as the Agent Tool Interface Over a Filesystem

Persistent storage for AI agent sandboxes that survives restarts requires a durable filesystem. Files can keep working memory between sessions, but keeping a running process needs full suspend-and-resume support. Bash over that filesystem gives models a familiar tool interface, but its usefulness depends on infrastructure that preserves state, isolates execution, and supports branching without rebuilding the environment.

Why bash is the interface models already know

Models are trained overwhelmingly on bash and POSIX tools, which makes the shell a natural interface for agent work. They already know how to navigate directories, search files, and connect commands into pipelines. That familiarity reduces the reasoning needed to act. Instead of translating each task into a less familiar interface, the model can work with commands and file paths it already understands. The filesystem becomes the contract between the agent and its environment.

Exposing that familiar interface lets existing tools run unmodified and gives the agent a consistent way to discover its surroundings. The infrastructure’s job is then to preserve the contract, including the files those commands read and change.

What collapsing tool surface actually means in practice

Every bespoke MCP tool occupies context before it does useful work. The model must understand its schema, recognise its errors, and decide when to choose it over another tool. More tools mean more decisions and more possible failures. Collapsing file-oriented work into bash reduces that burden and slows context rot, because the agent can discover context as it works rather than receive a catalogue of tool definitions upfront.

Searching logs on S3 makes the cost concrete. Through the S3 API, the agent must list objects, download them individually, and search them locally. Against a filesystem mount, it can use grep -r "ERROR" /mnt/logs/. With the API, the agent has to plan extra steps, spend tokens to spell them out, and think through the results along the way.

That does not make bash a replacement for every interface. Databases still handle queries over clean schemas, and there is still a place for typed API responses. Bash handles unstructured files, discovery, and pipelines, while databases handle data that benefits from a defined schema.

Why the filesystem choice forces the isolation question

An agent with bash can run arbitrary shell commands. With filesystem access, it can install packages, open network connections, read environment variables, and attempt privilege escalation. Those capabilities require a real security boundary. Shared-kernel containers keep processes apart, but a flaw in the host-kernel can put co-tenants at risk. CVE-2024-21626, known as “Leaky Vessels,” demonstrated why that boundary is inadequate for this threat model.

Different isolation primitives address that exposure in different ways. gVisor interposes a user-space kernel so that most syscalls never reach the host kernel. Google Kubernetes Engine’s Agent Sandbox mode uses it by default for AI workloads. The trade-off is workload-dependent. gVisor adds 10 to 30 percent overhead on I/O-heavy workloads, with minimal penalty on compute-heavy tasks. A Firecracker microVM instead gives the sandbox its own kernel, the boundary used by Archil for arbitrary agent execution. GPU workloads remain an exception where containers are the practical choice.

An agent with unrestricted outbound access can exfiltrate data even when it cannot escape its VM. Default-deny egress therefore belongs in the same evaluation as the isolation primitive, and credentials should be injected at the network boundary and kept outside sandboxed code. A provider should name its hypervisor, default egress policy, and secret location. “Secure sandbox” is a label that leaves the architecture unspecified.

How to persist files between AI sandbox sessions without losing agent state

An isolated sandbox that resets each session discards the context the agent has built. The agent has to rebuild crawled datasets, installed packages, conversation history stored in files, and work it had under way. Ephemeral execution works well for one-shot tasks, but coding agents and research workflows need their files and dependencies to survive between sessions.

Persistence and continuous runtime are separate properties. A durable volume can keep files after the process stops, so persistent working memory can survive without compute running all the time. Process memory is a different requirement. If an agent needs to resume the running process instead of starting another process with saved files, the platform needs full suspend-and-resume support. A volume attachment and a memory snapshot are not interchangeable promises.

Fly.io Sprites illustrates one persistent-storage design with Firecracker microVMs and 100 GB of storage per sandbox. Durable object storage keeps the persistent copy, and NVMe is a local cache. Sprites creates checkpoints in around 300 ms. Blaxel takes an interactive-workload approach, providing microVMs that boot in milliseconds and resume with very low latency. Archil builds persistent Firecracker microVMs with durable, forkable disks so that the filesystem contract survives across sessions and executions. The choice depends on what survives: saved files, process memory, or both.

How the filesystem enables parallelism and branching without full copies

Once state survives a session, agents can do more than return to yesterday’s work. They can explore several possible next steps from the same starting point. That requires cheap branches and reliable rollback. Copying an entire environment for each attempt adds hundreds of milliseconds to seconds per checkpoint, which becomes a bottleneck for deep tree search and large fan-outs. For test-time tree search and reinforcement learning, the required state includes both files and running processes.

A fork should take milliseconds no matter how big the disk is. Copy-on-write branching at the filesystem layer makes that possible without duplicating the full disk for each attempt. S3 versioning protects individual objects, but it does not give an agent an isolated, writable branch of a bucket. A filesystem-backed sandbox can provide the disk foundation for branching, while complete execution rollback still requires process-state support.

DeltaBox explores the similarity between successive sandbox states to make checkpointing fast and rollback faster. It aims to get operations down to single-digit or low-double-digit millisecond times without copying mostly unchanged state over and over. Crab addresses a related gap. Application-level recovery can preserve chat history while missing operating-system side effects, but full per-turn checkpoints are expensive under dense co-location. Crab uses an eBPF-based inspector to classify each turn’s OS-visible effects, align checkpoints with turn boundaries, and overlap checkpoint or restore work with LLM wait time. Qwen’s training infrastructure runs large numbers of isolated environments in parallel, where these costs add up across agents.

Connecting agents to large datasets without copying them into the sandbox

The filesystem contract also extends to data outside the sandbox. Mounting object storage as a POSIX filesystem lets agents use familiar commands without first copying the dataset into their environment. The data stays in place. Compared with downloading objects before processing, this removes a separate staging workflow and avoids duplicating the dataset as a prerequisite for access. With credentials managed outside the sandbox, it also removes the need to give the agent object-store credentials directly.

Amazon’s S3 Files mounts an S3 bucket into an agent’s local environment with a single command, using Amazon EFS infrastructure to provide full filesystem semantics without migration. Google’s Agent Compute Engine uses read-only mounts for base images, language toolchains, and shared package caches across sandboxes. Shared volumes can use high-speed FUSE on Google Cloud Storage, with credentials managed on the host. The abstraction is not tied to one object store. In Archil’s implementation, S3, GCS, R2, or Azure buckets appear as a POSIX filesystem, so grep, find, and pipelines work unmodified while writes sync back to the bucket in the background. That keeps the data interface readable by the rest of the stack.

An in-sandbox FUSE daemon holds live kernel-to-userspace connection state and live object-store credentials, neither of which serialises or restores cleanly through a VM memory snapshot. After resume, the mount is dead. The mitigation is a dedicated mount pod per volume outside the agent VM, a pattern used by several Kubernetes CSI implementations.

How the same filesystem model extends to multi-tenant agent products

A per-tenant microVM and filesystem volume turn tenant separation into part of the execution and storage design. Each agent’s filesystem, credentials, and process state belong inside its own boundary, rather than sharing an environment governed only by application checks. This puts isolation beneath the generated code. A misbehaving agent should not gain access to another tenant simply because it can issue shell commands.

Scope must come from authenticated context and remain intact through tools, databases, queues, caches, artifacts, credentials, and logs. A filesystem per tenant reduces the places where scope can be lost, but does not excuse mistakes in the remaining services. The storage partition and the authenticated identity must agree. Otherwise, a strong sandbox can still be attached to the wrong data.

Storage allocation needs to follow tenant activity as well. At thousands of tenants, workloads can vary unpredictably from kilobytes to gigabytes, making flat allocations wasteful for some and restrictive for others. Fully elastic storage that is metered on active use can grow and shrink with that use. When a tenant connects an existing bucket, the bucket should remain the source of truth, with infrastructure syncing in both directions. When access is revoked, the data should stay in the tenant’s account without having to be moved.

Choosing a sandbox on its infrastructure track record, not its launch date

A product’s launch date says little about the infrastructure it runs on. The stronger evidence is how long that infrastructure has run real production workloads at scale, and which failures its operators can name and explain resolving. Features describe how a system is meant to work. Production history reveals what happened when execution, storage, and recovery stopped cooperating. That difference matters for sandboxes because what they promise depends on several boundaries at once.

The practical evaluation starts with isolation and network access. A provider should identify the primitive, whether Firecracker, Kata Containers, gVisor, or a shared-kernel container, and name the hypervisor where applicable. It should state whether outbound traffic is allowed or denied by default and whether secrets reach the agent process or stay at the network boundary. Persistence needs equally plain answers. The description should distinguish filesystem durability from memory preservation, state any session time cap, and explain what happens to ephemeral data when execution pauses.

Branching and storage access complete the evaluation. Checkpoint and fork latency should be stated with whether they depend on disk size, and the platform should explain whether the same disk can be mounted on many machines simultaneously. Existing-bucket support should identify S3, GCS, R2, and Azure Blob where available, along with migration requirements and mount-credential location. Per-tenant isolation must cover both the application and storage. The final test is evidence that these properties work together under real load, including specific failure modes the infrastructure has encountered and resolved.