ack-agent-sandbox-manager-Container Compute Service(ACS)-阿里云帮助中心

ack-agent-sandbox-manager is an API server and agent sandbox proxy add-on that is compatible with the E2B protocol. This topic covers the basic information, usage instructions, and changelog for the ack-agent-sandbox-manager add-on.

Overview

ack-agent-sandbox-manager is an API server and agent sandbox proxy add-on that is compatible with the E2B protocol. It provides full-lifecycle management for sandboxes, including creation, management, pausing, and resuming.

Port matrix

The add-on creates different workloads based on the enabled features. If you have enabled NetworkPolicy or security groups, allow the corresponding traffic based on the following port matrix.

Inbound ports

Workload sandbox-manager (namespace: sandbox-system) contains the following containers and ports:

Container	Purpose	Listening address	Default port	Protocol	Configurable	Description
controller	E2B HTTP API (includes `/health` and `/metrics`)	`0.0.0.0`	8080	HTTP	`--port`	Used for the Liveness Probe. The Service does not directly expose this port.
controller	Envoy ext-proc and gRPC health check	`0.0.0.0`	9002	gRPC	No (constant)	Called by the local Envoy.
controller	Peer route synchronization`/refresh`	`0.0.0.0`	7789	HTTP	No (constant)	Used for the Readiness Probe and Startup Probe.
controller	Memberlist Gossip	`POD_IP`	7946	TCP and UDP	`--memberlist-bind-port`	Used for Gateway and Manager replica discovery and gossip communication.
controller	pprof profiling	Default: `6060`	6060	HTTP	`--enable-pprof` and `--pprof-addr`	Disabled by default.
envoy	External data plane and API entry point	`0.0.0.0`	7788	HTTP and WebSocket	Envoy ConfigMap	The only externally exposed port for the Service or Ingress.
envoy	Envoy Admin	`127.0.0.1`	9901	HTTP	Envoy ConfigMap	Local access only.

Kubernetes exposure: The Service or Ingress forwards only the 7788 port. The containerPort values declared in the Deployment include 8080, 9002, and 7788. Ports 7789 and 7946 are not declared.

Workload sandbox-gateway (namespace: sandbox-system) contains the following containers and ports:

Container	Purpose	Listening address	Default port	Protocol	Configurable	Description
gateway	External data plane and API entry point	`0.0.0.0`	7788	HTTP and WebSocket	No	The only externally exposed port for the Service or Ingress.
gateway	Prometheus endpoint, scrape path `/metrics`.	`0.0.0.0`	9902	HTTP	No	Monitoring metrics collection.
gateway	Envoy admin	`127.0.0.1`	9901	HTTP	No	Envoy Admin interface. Only allows local access within the Pod.
gateway	Peer route synchronization (POST `/refresh`), used for internal sandbox-manager route synchronization. `/readyz` is used for the Readiness Probe.	`0.0.0.0`	7789	HTTP	No	Peer route synchronization (POST /refresh), used by sandbox-manager to synchronize routing tables. Also provides the /readyz path for the Readiness Probe.
gateway	Memberlist Gossip	`0.0.0.0`	7946	TCP + UDP	No	Gateway and Manager multi-replica discovery and gossip communication.

After enhancedTrafficManagement is enabled for the add-on, the egress-gateway, gateway-controller, traffic-proxy, and traffic-extension workloads are created in the sandbox-traffic-system namespace. These workloads contain the following containers and ports:

Pod / Container	Purpose	Listening address	Default port	Protocol	Description
gateway-controller	Authentication xDS and certificate issuance	`0.0.0.0 / ::`	15012	TLS gRPC	Exposed through `gateway-controller.sandbox-traffic-system.svc:15012`.
gateway-controller	Metrics and control plane monitoring interface	`0.0.0.0 / ::`	15014	HTTP	Exposed through `gateway-controller.sandbox-traffic-system.svc:15014`.
traffic-proxy (ztunnel Sidecar, deployed in business Pods)	Prometheus metrics	ztunnel Pod; binding address determined by the ztunnel image	15020	HTTP	No Service exposed.
traffic-proxy	`/healthz/ready` Readiness Probe	ztunnel Pod; binding address determined by the ztunnel image	15021	HTTP	Used by kubelet for probing.
egress-gateway	Receives workload tunnel traffic	`0.0.0.0 / ::`	15008	TCP-based HBONE	Exposed by the Service.
egress-gateway	`/stats/prometheus` merged metrics	`0.0.0.0 / ::`	15020	HTTP	The egress gateway Service does not expose this port.
egress-gateway	`/healthz/ready` Readiness Probe	`0.0.0.0 / ::`	15021	HTTP	Exposed by the egress gateway Service.
egress-gateway	Envoy Prometheus listening port	Default `0.0.0.0 / ::`	15090	HTTP	The egress gateway Service does not expose this port.
traffic-extension	Envoy external processing and Layer 7 policy enforcement	Default `0.0.0.0 / ::`	9002	gRPC	Exposed by the Headless Service.
traffic-extension	gRPC health check	Default `0.0.0.0 / ::`	9003	gRPC	Used by liveness and readiness probes.
traffic-extension	Prometheus metrics	Default `0.0.0.0 / ::`	9090	HTTP	Exposed by the Headless Service.

Outbound ports

Workload sandbox-manager:

Source	Purpose	Target	Default port	Protocol	Condition
controller	Kubernetes API	`kubernetes.default.svc` or kubeconfig	443	HTTPS	Always enabled. Used for CRDs, Watch mechanisms, and Lease resources.
controller	Peer route synchronization	`<Peer PodIP>`	7789	HTTP	Multi-replica deployment.
controller	Memberlist join and gossip	`<Peer PodIP>`	7946	TCP and UDP	Always enabled.
controller	agent-runtime Sidecar	`<Sandbox PodIP>`	49983	HTTP	Operations such as claim, clone, and resume. Can be overridden using annotations.
controller	Sandbox application port (direct connection)	`<Sandbox PodIP>`	Business port (such as CDP 9222)	HTTP	API called on demand (such as BrowserUse).
controller	Quota Redis	`--quota-redis-addr`	Typically 6379	Redis or TCP	Optional. If not configured, fail-open is used by default.
controller	MySQL API Key storage	`E2B_KEY_STORAGE_DSN`	Typically 3306	MySQL or TCP	Enabled only when `--e2b-key-storage=mysql`.
envoy	ext-proc	`127.0.0.1`	9002	gRPC	Always enabled.
envoy	Local E2B API	`127.0.0.1`	8080	HTTP	Non-sandbox requests.
envoy	Sandbox user traffic	`<Sandbox PodIP>`	Mapped port	HTTP or WebSocket (ORIGINAL_DST)	Sandbox requests.

Workload sandbox-gateway:

Source	Purpose	Target	Default port	Protocol	Condition
gateway	Kubernetes API	`kubernetes.default.svc` or kubeconfig	443	HTTPS	Always enabled. Used for CRDs, Watch mechanisms, and Lease resources.
gateway	Peer route synchronization	`<Peer PodIP>`	7789	HTTP	Always enabled.
gateway	Memberlist join and gossip	`<Peer PodIP>`	7946	TCP and UDP	Always enabled.
gateway	agent-runtime Sidecar	`<Sandbox PodIP>`	49983	HTTP	The client needs to access the sandbox agent-runtime.
gateway	Sandbox user traffic	`<Sandbox PodIP>`	Mapped port	HTTP or WebSocket	Sandbox requests.

After enhancedTrafficManagement is enabled for the add-on:

Source	Purpose	Target	Default address	Port	Protocol	Condition
gateway-controller	Watches workload and configuration resources, reads and writes enabled certificate data	Kubernetes API Server	In-cluster API endpoint, typically `kubernetes.default.svc`	443	HTTPS	Always required
gateway-controller	Resolves hostnames used by egress policies	DNS resolver	`EXTERNAL_NAMES_CONTROLLER_DNS_SERVER`, or the nameserver in `/etc/resolv.conf`	53	UDP/TCP-based DNS	Always required
traffic-proxy	Receives xDS configuration and requests workload certificates	gateway-controller	`gateway-controller.sandbox-traffic-system.svc.<cluster-domain>`	15012	TLS gRPC	Always required
traffic-proxy	Sends selected client traffic to the designated egress gateway	Egress gateway	`egress-gateway.sandbox-traffic-system.svc`	15008	TCP-based HBONE	Always required
egress-gateway	Receives xDS configuration and requests workload certificates	gateway-controller	`gateway-controller.sandbox-traffic-system.svc`	15012	TLS gRPC	Always required
egress-gateway	Sends request attributes to the Extension for Layer 7 policy enforcement	traffic-extension	Default `traffic-extension.sandbox-traffic-system.svc.<cluster-domain>`	9002	gRPC	Always required
egress-gateway	Connects policy-allowed traffic to the original external target	Upstream target	Target address and request port		TCP, TLS, HTTP, or HTTPS	When traffic is allowed by the policy
traffic-extension	Watches SecurityProfile resources	Kubernetes API Server	In-cluster API endpoint, typically `kubernetes.default.svc`	443	HTTPS	When traffic-extension is enabled
traffic-extension	Retrieves sandbox identity tokens	Identity provider	`trafficExtension.identityProviderUrl`		HTTP or HTTPS	When the identity provider URL is configured
traffic-extension	Sends configured audit events	Audit Webhook	`URL rendered from the SecurityProfile`		HTTP or HTTPS	When the profile configures an audit webhook

Usage

For information about how to use ACS Agent Sandbox, see Create Agent Sandbox.

Changelog

July 2026

Version	Date	Description	Impact
v0.6.8	July 29, 2026	Features: Supports JWT Token issuance. When a sandbox is claimed through the E2B protocol, a JWT Traffic Access Token is issued and returned to the client. The gateway supports JWT signature verification based on Traffic Access Tokens. The gateway adds a `/readyz` interface on port 7789 as an HTTP-based Readiness Probe, ensuring that ready status (200 OK) is returned only after the JWT Verifier starts. Claimed sandboxes are labeled with the Owner ID (the ID of the API key). Added the GlobalSecurityProfile resource. SecurityProfile supports configuring priority using the `priority` field. Bug fixes: Fixed a rare issue where creating or deleting a key could fail when using a Secret as the API key storage backend. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK version 2.7.0 or later.	This upgrade does not impact your services.
v0.6.7	July 22, 2026	Features: Supports specifying the reclaim time for hibernated sandboxes: through extended metadata `e2b.agents.kruise.io/reserve-paused-sandbox-for` during creation, or through the extended header `x-e2b-kruise-reserve-paused-sandbox-for` during hibernation. The default is 100 years (no deletion). Valid values are positive duration strings, such as `30m`, `1h`, and `240h`. Supports multi-domain access. Supports Security Token Service token rotation under the E2B protocol for on-demand OSS storage mounting. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK version 2.7.0 or later.	This upgrade does not impact your services.
v0.6.6	July 7, 2026	Features: Supports specifying a full name or a fixed prefix for a cloned sandbox using the extended metadata `e2b.agents.kruise.io/sandbox-name` and `e2b.agents.kruise.io/sandbox-generate-name` during cloning. Supports setting quotas for API keys, including the number of sandboxes, total CPUs, and total memory. Supports using `sandbox-gateway` for inbound traffic authentication of sandboxes. The default data plane service for new clusters has been switched to `sandbox-gateway`. Optimizations: Reduced log volume by approximately 70%. Sandboxes that fail to be created are no longer retained during retries by default. Added a label (`agents.kruise.io/reserved-failed-sandbox`) for filtering failed sandboxes. These sandboxes are no longer returned by the `list`, `info`, and other query interfaces. Bug fixes: Fixed an issue where the `list` interface could not list all sandboxes in large-scale clusters. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK version 2.7.0 or later.	This upgrade does not impact your services.

June 2026

Version	Date	Description	Impact
v0.6.5	June 17, 2026	Features: Updated the Envoy log format for `sandbox-manager` and `sandbox-gateway` to provide more detailed connection information. `sandbox-gateway` now supports matching the upstream HTTP protocol with the downstream HTTP protocol. Bug fixes: Fixed a rare issue where the `snapshot` interface could incorrectly report an error when creating a checkpoint, leading to an interface failure and checkpoint leaks. When you use a secret as the storage backend for API keys, new keys take effect across all replicas almost instantly, with a possible millisecond-level delay. The `create` interface no longer retries on non-retriable errors, such as quota limits, when creating a sandbox directly. It now returns an error immediately. Added exponential backoff to the retry process of the `create` interface, which significantly reduces the number of retries for a single request. Deleting sandboxes with a False Ready status is now supported. Updated the base Envoy image for `sandbox-gateway` to v1.37.3 to fix CVE-2026-27135 and CVE-2026-47774. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK version 2.7.0 or later.	This upgrade does not impact your services.
v0.6.4	June 11, 2026	Features: Advanced traffic management: Supports man-in-the-middle (MITM) interception of HTTPS requests in conjunction with `ack-agent-identity`. SecurityProfile supports matching request schemes. SecurityProfile supports audit webhooks. SecurityProfile supports API key credential injection. SecurityProfile supports Alibaba Cloud STS token injection. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK version 2.7.0 or later.	This upgrade does not impact your services.
v0.6.3	June 9, 2026	Bug fixes: Removed the `createPodInsteadOfSandbox` feature. Features: Removed the default server-side timeouts for sandbox creation, including Claim Timeout and Wait Ready Timeout. These values are still configurable through metadata. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK version 2.7.0 or later.	This upgrade does not impact your services.
v0.6.2	June 5, 2026	Features: Added support for E2B SDK versions 2.25.0 and later. The `create sandbox` interface now enforces secure mode (accessToken authentication). Added an E2B key compatibility layer. New keys are now returned in a format that passes E2B client-side validation. Existing keys and custom admin keys can also be converted to the compatible format without data loss. Added support for persistent connections on the data plane, with a configurable idle timeout. Added a delayed exit feature to `sandbox-manager`. During rolling updates, old-pod termination can optionally be delayed for a smoother traffic transition. Optimizations: Extended the server-side Resume timeout to better handle large-scale resume scenarios under heavy load. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK version 2.7.0 or later.	This upgrade does not impact your services.
v0.6.1	June 1, 2026	Bug fixes: Fixed a rare issue where a process could panic if a user disconnected immediately after calling the `create` interface. Fixed an issue where an auto-paused sandbox could not be resumed using the `connect` interface. Features: Supports Layer 7 egress traffic control. A new SecurityProfile API allows you to intercept requests to an egress gateway through the `egress-control` runtime and filter them based on HTTP request attributes such as path and method. The `create` interface supports enabling sandbox IP address retrieval using the metadata `e2b.agents.kruise.io/return-sandbox-ip: "true"`. For sandboxes created with this metadata, query interfaces such as `create`, `list`, and `get_info` return sandbox information that includes the metadata entry `e2b.agents.kruise.io/sandbox-ip`, which contains the IP address of the sandbox. Supports HTTP access. HTTPS is not mandatory. The `create` interface supports configuring resource limits for a sandbox at creation time using the `e2b.agents.kruise.io/cpu-request` and `e2b.agents.kruise.io/cpu-limit` metadata. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade does not impact your services.

May 2026

Version	Date	Description	Impact
v0.6.0	May 15, 2026	Architecture refactoring: Architecture upgrade: Completely refactored `sandbox-manager` using controller-runtime. Optimized many existing implementations and improved test coverage to enhance correctness. Fixed numerous non-critical issues that were transparent to users. Removed the unnecessary internal Template Cache and SandboxSet Reconcile processes to improve claim performance and reduce memory consumption. Rewrote the underlying wait mechanism to support concurrent monitoring of Kubernetes resource states in complex scenarios. Features: Enhanced multi-tenancy capabilities: Added a Teams API to assign teams to an API key. Teams enable namespace-level resource isolation for different users (keys). Backward compatibility for existing keys with cluster-scoped permissions is maintained. Pause/Resume optimizations: The pause and connect interfaces now support high-concurrency calls. Multiple non-conflicting requests can merge their workflow status checks and return simultaneously without errors. Conflicting concurrent requests will still fail. The resume operation (`connect`) now always correctly sets the timeout, even if the resume process fails. Improved error messages: When the Create method fails, it returns detailed information for troubleshooting, often allowing you to identify the problem without checking logs. Compatibility notes: OpenKruise Agents version v0.3.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade does not impact your services.

April 2026

Version	Date	Description	Impact
v0.5.2	April 29, 2026	Features: Supports using MySQL as a storage backend for API keys. Supports custom CDP ports when you use the BrowserUse API. Supports `list` and `get` interfaces for templates. `sandbox-gateway` supports graceful shutdown using a custom OpenKruise API. Supports restoring dynamic storage mounts in checkpoint clone and resume scenarios. Added a significant number of Prometheus metrics to `sandbox-manager` to support sandbox dashboards. `sandbox-manager` now supports updating pod labels when claiming a sandbox. Performance optimizations: Optimized the performance of dynamic storage mounts by supporting parallel mounting. Bug fixes: Fixed an issue where a missing `runtime` field during snapshot creation caused the runtime not to be injected during cloning. Fixed an issue where `sandbox-gateway` did not support WebSocket. Fixed an issue where the `e2b file.watch_dir` method was unavailable. Fixed an issue that made `browser-use` unusable with the new authentication architecture. The new `connect` interface no longer shortens the timeout of a running sandbox, which aligns its behavior with the official E2B implementation. Compatibility notes: OpenKruise Agents version v0.2.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade does not impact your services.
v0.5.0	April 2, 2026	Features: Introduced `sandbox-gateway`. Supports listing and deleting snapshots (checkpoints). All `list` interfaces now support pagination using `limit` and `nextToken`. Restricted the api-keys series of interfaces to admin access only. `sandbox-gateway` now supports domain name matching. The add-on can now be configured to use either `sandbox-manager` (default) or the new `sandbox-gateway` for traffic forwarding. Supports re-mounting CSI storage after a sandbox is resumed based on E2B. Performance optimizations: Replaced the previous heartbeat mechanism with memberlist for inter-replica discovery. Bug fixes: During a claim, the WaitSandboxReady phase can now fall back to fetching the sandbox object from the API server once to handle scenarios with high informer sync latency. Upgrading the add-on or adjusting its configuration through the component center no longer triggers a rolling restart of all pods. Compatibility notes: OpenKruise Agents version v0.2.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade does not impact your services.

March 2026

Version	Date	Description	Impact
v0.4.3	March 23, 2026	Features: Supports restoring (cloning) from a checkpoint during creation. Supports creating a checkpoint using the `snapshot` interface. Supports re-initializing the runtime in scenarios where memory is not preserved. Bug fixes: When a sandbox is deleted, the proxies of all replicas are forcibly refreshed to remove the corresponding route entries. Compatibility notes: OpenKruise Agents version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade does not impact your services.
v0.4.2	March 13, 2026	Features: Supports mounting NAS volumes. Compatibility notes: OpenKruise Agents version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade does not impact your services.
v0.4.1	March 12, 2026	Features: The create-on-no-stock feature is now enabled by default. If no instances are available in the SandboxSet warm pool, a new instance is automatically created. You can disable this feature by setting `e2b.agents.kruise.io/create-on-no-stock = "false"`. Added a new extended protocol, `e2b.agents.kruise.io/never-timeout`. If set to `"true"`, the sandbox never expires and its timeout cannot be modified by any setting. Performance optimizations: Optimized the time complexity relative to concurrency from O(n) to O(1), which significantly improves claim performance. Added new Prometheus metrics. Changed the DNS Policy to Default to resolve network access issues in very large clusters. Compatibility notes: OpenKruise Agents version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade does not impact your services.
v0.4.0	March 2, 2026	Features: [Breaking Change] Removed the `e2b.agents.kruise.io/should-init-envd` annotation from SandboxSet. Envd is now initialized automatically by default. For custom images that do not require envd initialization, you must explicitly skip the initialization process using the `skip-init-runtime` parameter. Added the following E2B extended protocols: `e2b.agents.kruise.io/create-on-no-stock`: Creates a new sandbox instance immediately if no instances are available in the warm pool, instead of waiting for the warm pool to be replenished. Default value: `false`. `e2b.agents.kruise.io/wait-ready-timeout-seconds`: Specifies the time to wait for a sandbox to become ready. Default value: 30 seconds. `e2b.agents.kruise.io/skip-init-runtime`: Skips runtime (envd) initialization. Default value: `false`. `e2b.agents.kruise.io/reserve-failed-sandbox`: Preserves a failed sandbox instance after a claim for debugging. Default value: `false`. `e2b.agents.kruise.io/claim-timeout-seconds`: Specifies the maximum retry time for a backend sandbox claim operation. Default value: one minute. SandboxSets with the same name across multiple namespaces can now serve as a single template. Bug fixes and optimizations: [Breaking Change] The sandbox-manager add-on only indexes allocated Sandboxes with the label `agents.kruise.io/sandbox-claimed=true`. For existing allocated sandboxes that do not have this label, calls to the CRUD or pause/resume APIs will return a 404 error. The server-side Sandbox Claim retry now stops correctly after the client disconnects. Significantly improved the efficiency and correctness of Kubernetes event processing and indexing. Added a fallback scheduled garbage collection (GC) logic for the routing table to prevent memory leaks caused by lost sandbox Delete events. Compatibility notes: OpenKruise Agents community version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This version contains breaking changes. Please read the changes carefully before upgrading.

January 2026

Version	Date	Description	Impact
v0.3.1	January 20, 2026	Features: Supports dynamic PV mount. Compatibility: Community OpenKruise Agents version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade has no impact on your services.
v0.3.0	January 13, 2026	Features: Supports E2B SDK version 2.8.1. This adds the `connect` interface, supports the `auto_pause` mode for the client's `beta_create` method, and aligns the timeout calculation with E2B. Adds extended features to the `create` interface. You can now trigger in-place image upgrades and dynamic Container Storage Interface (CSI) mounts when creating a sandbox. Optimizes delivery in high-concurrency scenarios. This significantly reduces invalid API Server requests, supports large request queues, and improves the delivery success rate. Adds strong consistency state synchronization between replicas after hibernation and wake-up operations. Supports custom E2B protocols. This removes the dependency on wildcard domain resolution and wildcard certificates. Removes gateway authentication. The authentication logic is moved to the runtime. Compatibility: Community OpenKruise Agents version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade has no impact on your services.

December 2025

Version	Date	Description	Impact
v0.2.0	December 16, 2025	Features and optimizations: Rewrote the cache indexing logic to significantly improve performance. Refactored the sandbox Create, Read, Update, and Delete (CRUD) logic based on the new cache. This greatly reduces optimistic locking conflicts and improves interface response speed. Added compatibility for several E2B interfaces and parameters. Added expectation-based filtering for dirty cache data. This reduces abnormal retries caused by delayed informer updates and is highly effective in high-concurrency scenarios. Added support for cross-namespace sandboxes. This lets you manage sandbox resources across the entire cluster. Added support for customizing the maximum value of the E2B timeout parameter. This applies to interfaces such as `create`, `timeout`, and `connect`. Compatibility: Community OpenKruise Agents version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade has no impact on your services.
v0.1.0	December 4, 2025	Features: Added an API Server for sandbox management that is compatible with the E2B protocol. Added an agent sandbox proxy. Compatibility: Community OpenKruise Agents version v0.1.0. E2B SDK versions 2.7.0 to 2.24.0.	This upgrade has no impact on your services.