How Agent Sandbox Achieves Instance-Level OSS Isolation with On-Demand Mounting

Background: Why Agents Need Sandboxes

Letting LLMs write and execute code autonomously carries risk because the executed content cannot be predetermined. The industry standard is to provide a sandbox — an isolated, ephemeral execution environment (open-source examples include E2B; Agent Sandbox is Alibaba Cloud Container Service's managed form, compatible with E2B interfaces). Sandboxes solve execution safety but are stateless: instances can be destroyed and recreated at any time, causing local data to disappear. This leads to a fixed pattern — compute in the sandbox, data in object storage, connected via mounting.

Two Core Business Scenarios

From observed agent platforms, requirements cluster into two categories:

Cross-instance read-only sharing — enterprise knowledge bases, public skill libraries, and dependency distribution. Multiple instances concurrently read the same copy, avoiding per-instance downloads that slow cold starts.

Instance-exclusive read-write — code interpreter and analysis task input retention and artifact persistence, long-task sleep/wake resumption continuing the same working directory.

Multi-tenant platforms add a third requirement: each user's data must be visible only to their own instances. This is the core problem the permission design addresses. A single solution struggles to satisfy both categories plus scale-driven management overhead, so a layered approach is needed.

AgenticBucket: One Instance, One Storage Space

Multi-tenant isolation demands that each instance's data be mutually invisible. OSS Agentic Bucket introduces a two-layer bucket architecture that pushes isolation down one level:

AgenticBucket (management layer) — serves only as a template and container, centrally managing default configurations such as ACL, encryption, and versioning.

BucketSpace (data layer) — the actual storage space. Created inheriting upper-layer config, thereafter behaving exactly like a standard Bucket — both data plane and control plane reuse standard OSS interfaces, requiring no new API adaptation.

Difference from Subpath Isolation

A regular Bucket can also isolate, but the difference lies in where isolation lands.

Regular Bucket + subpath isolates at the bucket-internal path level: different instances' data coexist in one bucket, distinguished by subpaths. The boundary exists only in policy description.

AgenticBucket sinks isolation to the storage space level: each instance owns an independent BucketSpace; the boundary is the space itself, no longer relying on correct path partitioning. One is path-level isolation, the other space-level; a policy misconfiguration in the former can affect other instances in the same bucket, while the latter limits impact to the instance's own space.

Comparison of the two approaches:

Isolation level : Regular Bucket + subpath uses bucket-internal path; AgenticBucket uses independent BucketSpace.

Misconfiguration blast radius : Regular Bucket + subpath may affect other instances in same bucket; AgenticBucket limited to this instance's space.

Bucket-level config (encryption/versioning/ACL) : Regular Bucket + subpath shares config across whole bucket; AgenticBucket configures once at management layer, inherited by each space.

PV count : Regular Bucket + subpath planned per bucket; AgenticBucket uses one PV to serve all instances.

The two are not mutually exclusive: cross-instance shared data belongs in a regular Bucket with read-only mounts; AgenticBucket solves the separate need — each instance needing its own private space. The later configuration example shows both coexisting.

When to Choose AgenticBucket

Use AgenticBucket when any of the following apply:

Hard multi-tenant isolation — different users' data must not share a namespace, and isolation effectiveness must not depend on whether policies are written correctly.

Private spaces created on demand — instances launch dynamically at large scale with short lifecycles; no desire to pre-create directories or pre-plan naming.

One template serves all users — PV and SandboxSet do not grow with user count; switching users only changes bucketSpacePrefix.

Unified storage config inheritance — encryption, versioning, ACL configured once at management layer, inherited by all instance spaces.

Govern data by instance — audit, cleanup, export need to address by instance; independent spaces align easier than path prefixes.

Compliance requires permission boundary = storage boundary — must prove "one instance, one space" rather than "one bucket, differentiated by path".

Conversely, a regular Bucket suffices when: data already resides in an existing bucket with no migration plan; only multi-instance shared read is needed; instance count is low and tenant boundaries are insensitive; or component versions don't yet meet requirements.

Prerequisites : Only Agent Identity authentication supported (no AccessKey); RRSA OIDC must be enabled with required component versions; usable prefix length = 63 minus account ID, region ID, and fixed suffix; cross-region mounting requires explicit full name; capacity.storage currently ineffective, cannot be used for capacity quotas; request AssumeRoleWithOIDC quota per instance scale. Full steps and limits in reference [1].

Agent Identity: The Credential Challenge

After storage is partitioned per instance, the next question: by what credentials does an instance access its own space?

The naive approach mounts long-lived AK/SK as a Secret into the container (Figure A). Functional, but leaked credentials remain valid long-term; when many sandboxes share the same key set, the risk scope covers the entire bucket.

STS temporary credentials solve "long-lived" but not "over-permissioned": if all sandboxes still assume the same RAM role, they obtain identical permissions for the token's validity period.

Agent scenarios truly need: the data scope is determined at instance runtime, and permissions shrink to that user, that Bucket or BucketSpace, that subpath. ACS Agent Sandbox splits the answer into three layers: AgenticBucket provides instance-level storage space, Agent Identity decides "who can mount and how much", on-demand mounting decides "when and what".

Figure B shows the concrete chain: Sandbox-A and Sandbox-B mount different directories under the same Bucket, each completing identity issuance and credential exchange, receiving permissions covering only their own directory.

Administrators configure a maximum permission boundary once on the RAM role. Which specific bucket and subpath a given instance can access is automatically rendered by the component into a narrowed policy based on its mount configuration (input methods described next).

Final effective permission = admin-configured boundary ∩ auto-rendered instance policy.

This design yields dual benefits: admins need not write per-instance policies, and auto-rendering cannot exceed the boundary — the intersection keeps the boundary under admin control. Configuration burden is also lighter: the PV only declares authType: agent-identity, no Secrets required.

On-Demand Mounting: Mount Config Not in Template

With space and credentials settled, the final question: when and by whom are these configurations supplied? Agent Sandbox uses SandboxSet as the instance template (analogous to Deployment/Pod), with actual instances claimed via SandboxClaim.

If mount config were baked into the template, serving different users with different buckets would require maintaining multiple templates.

On-demand mounting defers this decision to the moment of instance claim — mount configuration travels with the creation request, so one template serves all scenarios:

Kubernetes native: write into SandboxClaim's spec.dynamicVolumesMount.

E2B SDK: pass via e2b.agents.kruise.io/csi-volume-config annotation.

Both share identical field structure; only the entry point differs.

Thus a single template can launch instances with varied mounts: different users mount their own workspaces; a single instance can simultaneously mount a read-only public library and a read-write private directory — directly matching the two earlier needs: cross-instance shared read-only and instance-exclusive read-write.

Beyond creation-time mounting, hibernation wake-up and in-place image upgrade runtime mounts are also covered, allowing long tasks to resume their original working directory after interruption.

Configuration Example

The three capabilities converge in a single mount declaration. The following instance mounts three points, covering both "cross-instance sharing" and "instance-exclusive" needs:

dynamicVolumesMount:
  # Shared public skill library (regular Bucket, read-only)
  - pvName: oss-pv-shared-skills
    mountPath: "/shared-skills"
    subPath: "skills"
    readOnly: true
    attributes: { credentialProviderName: "oss-shared-ro" }

  # This instance's exclusive skill directory (BucketSpace subpath, read-only)
  - pvName: oss-pv-agentic
    mountPath: "/skills"
    subPath: "skills"
    readOnly: true
    attributes:
      credentialProviderName: "oss-bs-subpath-ro"
      bucketSpacePrefix: "sbx-user-a"

  # This instance's workspace (BucketSpace subpath, read-write)
  - pvName: oss-pv-agentic
    mountPath: "/workspace"
    subPath: "workspace"
    attributes:
      credentialProviderName: "oss-bs-subpath-rw"
      bucketSpacePrefix: "sbx-user-a"

Here oss-pv-agentic (a single PV) is reused twice, differing only in subPath and read/write permission. Switching to another user's sandbox only requires changing bucketSpacePrefix; the PV needs no modification.

Summary

AgenticBucket decides where data lives, Agent Identity decides how far credentials reach, on-demand mounting decides what gets mounted. Stacked together, agent storage shifts from "pre-provisioned shared disk" to "on-demand private space"; leakage impact shrinks from all data with long-lived validity to a single instance, single path, expiring with the token.

The three layers can be adopted incrementally, not all at once. For multi-tenant, large-scale agent launch scenarios, this combination currently fits the security baseline best. Returning to the opening two needs: shared read-only lands on regular Bucket, instance-private lands in each BucketSpace; what to mount, which credentials to use, where data resides — all decided at the moment the instance is claimed.