#Introduction

Alauda Build of Agent Sandbox provides a Kubernetes-native way to manage isolated, stateful, singleton workloads with a stable identity. It is designed for AI agents, notebooks, development environments, and automation systems that need to execute code or tools in a dedicated runtime environment.

The current release is a Tech Preview for ACP v4.4. The product and ModulePlugin version is v0.5.4-1, based on upstream Agent Sandbox v0.5.4.

#What Agent Sandbox Is

Agent Sandbox is a sandbox orchestrator. You declare a Sandbox custom resource, and the controller manages the corresponding Pod and its lifecycle. The Sandbox API provides a stable name and status model for a single workload that does not fit the replicated model of a Deployment or the ordinal identity model of a StatefulSet.

Agent Sandbox does not implement a container runtime. Runtime isolation remains the responsibility of the runtime selected by the workload, such as the default OCI runtime, gVisor, or Kata Containers. Use Kubernetes RuntimeClass to select that runtime.

#When to Use Agent Sandbox

Use Agent Sandbox when a workload needs one or more of the following characteristics:

• Execute user-provided scripts, LLM-generated code, browser automation, or third-party tools.
• Keep a stable workload identity across controller reconciliation.
• Suspend and resume an execution environment through a declarative API.
• Attach persistent storage to an isolated, single-instance workload.
• Pre-create environments with a warm pool when the optional extension controllers are enabled.
• Apply a stronger runtime boundary, such as Kata Containers, to higher-risk tasks.

A trusted agent that only calls external APIs usually does not need a Sandbox. A normal Deployment is simpler for stateless, replicated application services.

#Current Scope

The core Sandbox resource is available by default. The following extension resources are optional and require controller.extensions=true:

• SandboxTemplate defines a reusable Sandbox workload template.
• SandboxWarmPool keeps prepared workloads available for claims.
• SandboxClaim requests a Sandbox from a template or warm pool workflow.

Agent Sandbox complements Kubernetes security controls. Continue to use least-privilege RBAC, Pod Security, NetworkPolicy, trusted images, resource limits, and audit controls.

#Current Limitations

The Tech Preview does not provide the following productized capabilities:

• An external HTTP API gateway for clients that should not access Kubernetes APIs.
• Native idle shutdown based on request activity, CPU usage, or heartbeats.
• A snapshot mechanism that preserves packages or operating-system changes inside a container environment.

shutdownTime is an absolute RFC3339 expiration timestamp. It is not an idle timeout and is not automatically renewed by commands or network activity. PersistentVolumeClaims preserve data stored on the volume, but they do not snapshot the container image or runtime filesystem.