About Filestore agent volumes

Filestore agent volumes are a fully managed, high-density elastic NFS file storage capability built for stateful AI agent sandboxes, autonomous agent fleets, and multi-agent developer environments.

Filestore agent volumes provide the persistent storage layer required to maintain state, context, and history across agent executions, enabling low latency workloads, high density compute utilization, and strong sandbox isolation. Filestore agent volumes can also be used for any agent workspace or scratchpad needs, because agents natively work on file systems.

While designed primarily for AI agent workloads and developer sandboxes, volume pools and volumes also provide a general-purpose file storage architecture for applications that require multiple lightweight, independent file systems.

Use cases

Filestore agent volumes are designed for architectures that require numerous lightweight, fast-mounting file systems. Common use cases include:

  • Stateful AI agent sandboxes: Provide persistent storage for interactive coding agents and autonomous workflows, supporting under 100 ms volume reattachment across suspend and resume cycles.
  • Collaborative multi-agent swarms: Enable teams of specialized agents to work concurrently on shared repositories with POSIX-compliant ReadWriteMany (RWX) access and byte-range locking.
  • High-density developer environments: Host multi-tenant cloud IDEs and developer sandboxes, scaling up to one million isolated volumes backed by a single regional capacity pool.
  • Ephemeral CI/CD and automated testing: Provision short-lived, isolated storage for test runners and build pipelines with sub-second API turnover.
  • Secure execution of untrusted code: Run model-generated code safely within gVisor container sandboxes on GKE, using root squashing (root_squash) to protect underlying storage.

Stateful agent workflow on GKE

The following diagram illustrates how Filestore agent volumes, Private Service Connect (PSC), and GKE work together during an agent session:

Workflow showing Filestore agent volumes on GKE
Figure 1. Workflow showing how Filestore agent volumes work with GKE.
  1. The GKE cluster communicates with the managed storage plane through PSC service connection policies. All storage and NFS traffic remains private within your Virtual Private Cloud (VPC) network without requiring external IP addresses or VPC peering.
  2. A regional volume pool reserves shared capacity and IOPS for your project. When an agent session is requested, an individual volume is provisioned from the pool using the Filestore CSI driver or API in under a second.
  3. GKE schedules a container pod isolated with gVisor. The Filestore CSI driver attaches and mounts the volume to the pod's workspace directory (such as /workspace) in under 100 ms.
  4. The agent initializes inside the sandbox, immediately accessing its dedicated file system to clone Git repositories, install packages, and write scratchpad artifacts. When the agent becomes idle, GKE can terminate the compute pod to save costs while the volume preserves all workspace state for instant resumption.

Core capabilities

Filestore agent volumes deliver the following core capabilities:

  • Ultra-high volume density: Provision up to 1 million independent volumes within a single regional volume pool.
  • Sub-second operations: Create and delete volumes in under one second using REST APIs, matching the ephemeral lifecycle of autonomous agent tasks.
  • Storage attach under 100 ms: Mount existing volumes into pre-warmed sandboxes in under 100 ms, enabling instant interactive user sessions and high utilization of compute infrastructure.
  • POSIX compliance and RWX sharing: Provide NFSv3 file system semantics, directory hierarchies, and byte-range file locking across multiple containers and nodes.
  • Private VPC connectivity: Connect securely to your VPC network using Private Service Connect (PSC) service connection policies.

Volume pool and volumes

Filestore agent volumes introduce a simplified two-tier resource model. The underlying storage infrastructure is managed for you, so you don't need to manage or configure file server instances:

  1. Volume pool: The top-level managed regional resource. A volume pool reserves a shared pool of storage capacity and IOPS for a project and VPC network, and enforces default volume quota policies.
  2. Volume: The individual, POSIX-compliant storage resource provisioned inside a volume pool. Each volume represents an isolated file system that can be mounted into one or more containers, pods, or VMs.

Supported workload patterns

You can integrate Filestore agent volumes into your architectures using several orchestration models:

  • GKE Agent Substrate: Use GKE Agent Substrate to manage the lifecycle of stateful agent sandboxes. Agent Substrate suspends idle agents to save compute costs and resumes them in under a second, while Filestore agent volumes persist the workspace file system state across suspend and resume operations. For more information, see Use Filestore agent volumes with GKE Agent Substrate.
  • GKE Agent Sandbox: Use GKE Agent Sandbox to manage the lifecycle of isolated, stateful agent environments with pre-warmed sandbox pools. For more information, see Use Filestore agent volumes with GKE Agent Sandbox.
  • Dynamic storage late-binding: For latency-critical interactive platforms, inject pre-provisioned NFS volumes into pre-warmed running sandbox pods in under 100 ms using host daemons and mount propagation, eliminating pod restart latency. For more information, see Use Filestore agent volumes with Agent Sandbox dynamic storage late-binding.
  • Self-managed GKE workloads: Deploy standard Kubernetes Deployment, StatefulSet, or Job workloads with PersistentVolumeClaim (PVC) resources backed by the Filestore CSI driver and volume pool StorageClass resources. For more information, see Use Filestore agent volumes with self-managed GKE workloads.

What's next