Overview of network access control for sandbox instances - Agent Sandbox

Overview

Network access control is divided into two categories based on the request direction:

Inbound access: External clients access the services that run in a sandbox. Public access (the default public endpoint and a custom public domain name) and private access are supported.
Outbound access: Programs that run in a sandbox access external services or internal network resources. A fixed egress IP, VPC access, L7 network access control, and L7 credential replacement are supported.

The following table describes the scenarios and configuration entries of each capability:

Direction	Capability	Scenarios	Configuration entry
Inbound	Public access	Exposing an agent preview (web UI, API, or demo) to the Internet, browser access or remote debugging, webhook callbacks that reach a sandbox, and temporary joint debugging across multiple clients.	Public Access
Inbound	Custom public domain name	Production environments that expose sandbox services through a fixed domain name, or that access the web services in a sandbox by using a custom HTTPS certificate.	Custom Domains
Inbound	Private access	Access from an enterprise intranet or office network. Compliance scenarios that require a sandbox not to be exposed to the Internet. An internal integrated development environment (IDE) or platform that reaches a sandbox only over a dedicated line or an internal domain name.	Private Access
Outbound	Fixed egress IP	The destination site or API requires a source IP address allowlist, or a third-party service accepts only a fixed egress address.	Configure a fixed public IP for a sandbox instance
Outbound	VPC access	Direct access to private resources and internal APIs in a VPC, such as ApsaraDB RDS, ApsaraDB for Redis, Message Queue for Apache Kafka, and File Storage NAS. Also used to connect a hybrid cloud network.	VPC network configuration
Outbound	L7 network access control	Allowing access only to allowlisted domain names or APIs, preventing data leakage, establishing a security baseline for sandboxes that run production code, and narrowing the egress scope dynamically per task.	Network Access Control
Outbound	L7 credential replacement	Real credentials do not need to be placed in the sandbox instance as environment variables, files, or code.	Outbound request header transformation

How it works

Inbound access

Inbound access paths of a sandbox instance

Inbound access provides three methods: the default public endpoint, a custom public domain name, and the private network. The following table uses the China (Beijing) region as an example to describe the control plane and data plane endpoints of each method:

Access method	Control plane endpoint	Data plane endpoint	Description
Default public endpoint	`https://api.cn-beijing.sandbox.aliyuncs.com`	`getHost(port)` → `cn-beijing.sandbox.aliyuncs.com`	Services in the sandbox are accessed directly over the Internet.
Custom public domain name	`https://api.example.com`	`https://{port}-{sandboxId}.example.com`	Requires a Canonical Name (CNAME) record and an HTTPS certificate that covers `*.example.com`.
Private network	`https://api.cn-beijing-vpc.sandbox.aliyuncs.com`	`getHost(port)` → `cn-beijing-vpc.sandbox.aliyuncs.com`	An interface endpoint for PrivateLink must be created first. Both the control plane and the data plane use domain names that contain `-vpc`.

After an inbound request reaches the sandbox instance, it can access two types of entries. One is the control API envd, the control plane service inside the sandbox that serves SDK operations such as commands and files. The other is the application service port, which provides the services running in the sandbox over HTTPS or WebSocket. The two types of entries are authenticated independently:

Application service: Public access is allowed by default. If allowPublicTraffic=false is set, requests to the public endpoint must carry trafficAccessToken in the e2b-traffic-access-token request header. The token is returned when a sandbox is created, connected, or resumed (create, connect, resume), but not by getInfo or list. Save the token together with sandboxId.
Control API: If secure=true is set, the SDK must carry envdAccessToken in the X-Access-Token request header to access envd. The token is returned when the sandbox is created and when the sandbox details are retrieved. The SDK adds the header automatically, so the application does not need to obtain or pass the token.

If allowPublicTraffic=false is set, secure=true must also be set. Otherwise, SDK access to the control API over the public endpoint is also blocked, and operations such as commands and files return 403.

Outbound access

Outbound access paths of a sandbox instance

A program in the sandbox, such as curl, a business SDK, or a database client, initiates an outbound request. It first passes through egress access control, the L7 network access control capability described in the Overview section. allowInternetAccess, allowOut, and denyOut jointly determine egress access control. The request then uses one of the following egress paths based on the destination:

Public egress: This path accesses external services on the Internet directly.
VPC egress: This path accesses private resources and internal APIs in the same VPC through VPC connectivity (vSwitch and security group). Typical targets include ApsaraDB RDS, ApsaraDB for Redis, Message Queue for Apache Kafka, and File Storage NAS. The VPC must be in the same region as the sandbox instance.
Fixed egress IP (NAT): The VPC route table points to an Internet NAT gateway. After Source Network Address Translation (SNAT), requests egress through the elastic IP address (EIP) associated with the gateway, and present a fixed public IP address to destinations.

L7 credential replacement takes effect during egress access control: By specifying network.rules, the platform can add or override request headers, or replace credential placeholders in header values.

The fixed public IP address is the source address of outbound requests from the sandbox. For both VPC egress and the fixed egress IP (NAT) path, routes, security groups, and access permissions must be configured based on the destination.

Usage notes

Network configurations are passed in when a sandbox instance is created. Some parameters support runtime updates:

allowInternetAccess, allowOut, denyOut, and network.rules are replaced as a whole by updateNetwork. The new configurations are not merged with the original rules.
allowPublicTraffic can be set only at creation time and cannot be modified after the sandbox instance is created.