Connect to Agent Sandbox using the E2B SDK

Background information

ACS Agent Sandbox is compatible with the E2B SDK. Use the E2B SDK to create, manage, and connect to sandbox instances. Agent Sandbox implements E2B protocol compatibility based on OpenKruise Agents and supports two E2B protocols:

• Native Protocol: Each sandbox uses a dedicated subdomain per port. The access format is <PORT>-<SANDBOX_ID>.DOMAIN, and the API endpoint is api.DOMAIN. Wildcard DNS resolution and TLS certificates are required. Suitable for production environments.

• Private Protocol: All sandboxes share a single domain and are distinguished by URL path. The access format is DOMAIN/kruise/<SANDBOX_ID>/<PORT>, and the API endpoint is DOMAIN/kruise/api. Only a single domain is required, which simplifies network configuration and reduces certificate cost.

Install components

1. Log on to the ACS console. In the left navigation pane, click Clusters.

2. On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Add-ons.

3. Install the Ingress controller and sandbox-related components.

   1. Install an Ingress controller.

      Install an Ingress controller component supported by ACS to access the sandbox-manager service from outside the cluster. The following steps use Install the ALB Ingress Controller as an example to create a new public-facing ALB instance.

   2. Install the ack-agent-sandbox-controller component.

      When you install this component for the first time, you must grant the AliyunCSManagedAgentSandboxRole role permissions to access your cloud resources. You can use the default parameter settings. If you require higher concurrency, you can increase the resource specifications.

      For more information about the features of this component, see ack-agent-sandbox-controller.

   3. Install the ack-sandbox-manager component.

      1. Prepare an E2B domain name.

         For more information about preparing a domain name, configuring DNS resolution, and applying for a certificate, see Use in a production environment.

      2. Configure the component parameters.

         Change className to alb (the IngressClass that is automatically created when you install the Ingress controller component), change domain to your actual domain name, and change adminApiKey to a custom API Key. Keep the other configurations at their default values. After the component is installed, an Ingress named sandbox-manager is created in the sandbox-system namespace.

         Parameter details

         Parameter	Parameter	Description
         sandboxManager	replicaCount	Number ofsandbox-manager instances. Default: 3.
         E2B	domain	The E2B domain name. For more information, see Prepare a domain name.
         	Enable E2B_API_KEY verification	Specifies whether to enable API_KEY authentication. This feature is enabled by default.
         	adminApiKey	If authentication is enabled, this parameter sets the initial key for the first installation. Replace the default value with your custom API key.
         Controller	logLevel	The log level of the controller. Default: 1.
         	resources.requests.cpu	The CPU resource request for the controller. Default: 2.
         	resources.requests.memory	The memory resource request for the controller. Default: 4 Gi.
         Proxy	resources.requests.cpu	The CPU resource request for the proxy. Default: 2.
         	resources.requests.memory	The memory resource request for the proxy. Default: 4 Gi.
         Ingress	className	The IngressClass name configured in the cluster, such as alb, mse.

      3. If you use the ALB Ingress controller, you must also add an HTTPS:443 listener for both the ALB instance and the Ingress.

         Update the AlbConfig to add anHTTPS:443 listener for the ALB instance.

         1. In the navigation pane on the left, choose Workloads > Custom Resources. On the Resource Objects tab, search for and click AlbConfig.

         2. In the list of AlbConfig resource objects, find the target resource alb, and click Edit YAML in the Actions column to its right.

         3. Add the spec.listeners.port: 443 and spec.listeners.protocol: HTTPS fields, then click OK.

            spec:
              config:
                addressAllocatedMode: Fixed
                addressType: Internet
                zoneMappings:
                  - vSwitchId: vsw-xxx
                  - vSwitchId: vsw-xxx
              listeners:
                - port: 80
                  protocol: HTTP
                - port: 443
                  protocol: HTTPS

         Update the Ingress to associate the HTTPS:443 listener.

         1. In the left navigation bar, select Network > Ingresses. In the Actions column for the sandbox-manager ingress, click Update.

         2. Add the following configuration, and click OK.

            • Annotations: alb.ingress.kubernetes.io/listen-ports: [{"HTTP": 80}, {"HTTPS": 443}]

Step 1: Create a warm-up pool

1. In the navigation pane on the left, choose Custom Resources. On the CRDs tab, click Create from YAML.

2. Create a SandboxSet resource by using the following YAML. The ack-sandbox-manager automatically detects this resource and initializes a sandbox template configuration named code-interpreter.

   To enable dynamic storage mounting, you must allow privileged containers and access to the hostPath (/var/run/csi). You can submit a ticket to have the security restrictions lifted. However, you must assume responsibility for the associated security risks. For more information about this mechanism, see the shared responsibility model.

   apiVersion: agents.kruise.io/v1alpha1
   kind: SandboxSet
   metadata:
     name: code-interpreter
     namespace: default
   spec:
     runtimes:
     - name: csi           # Supports CSI mounting. The corresponding sidecar is injected into new sandboxes.
     - name: agent-runtime # Injects environment management tools such as envd.
     replicas: 4
     template:
       metadata:
         labels:
           alibabacloud.com/acs: "true"
           alibabacloud.com/compute-class: agent-sandbox # Agent Sandbox instance type. 
           alibabacloud.com/compute-qos: default # Compute QoS: default or best-effort.
       spec:
         automountServiceAccountToken: false
         containers:
         - image: registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/code-interpreter:v1.6 # Replace the region with the one where your cluster is deployed.
           imagePullPolicy: IfNotPresent
           name: sandbox
           resources:
             limits:
               cpu: "1"
               memory: 1Gi
             requests:
               cpu: "1"
               memory: 1Gi
               ephemeral-storage: 30Gi
         terminationGracePeriodSeconds: 30

   Using the code-interpreter image

   • Image pull: The registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/code-interpreter image is a sample image that ACS created based on the e2b-code-interpreter project. It is compatible with the run_code interface of the E2B client. To improve the image pull speed, you can change the region in the image address to your actual region or remove -vpc to pull the image over the public network.

     Important

     This image is for demonstration and testing purposes only and is not recommended for production environments. If you need to deploy it in a production environment, perform the necessary security hardening, performance optimization, and feature enhancements to meet your security and stability requirements.

   • Use a custom image: If you want to use the E2B code-interpreter image, either directly or as a base image, use a versioned image provided by ACS. ACS does not guarantee runtime compatibility with the officiallatest image from E2B. If you need to use a custom image, ensure it meets the following conditions:

     1. Contains basic commands such ascp,mv, andmkdir.

     2. Includes bash, and the executable file is located at /bin/bash.

     When you use custom images, the run_code method of E2B is temporarily unavailable.

3. Click Pods in the left navigation bar, select the corresponding namespace, and view the created code-interpreter Sandbox.

   You can view SandboxSet resources by running the kubectl get sbs command, where AVAILABLE indicates the number of ready Sandboxes.

Step 2: Install the E2B SDK

The E2B SDK supports multiple programming languages, including Python, Java, and Go. This topic uses Python as an example. For detailed integration guides in other languages, see e2b-client.

1. Install the Python runtime.

2. Install the E2B Python SDK. Agent Sandbox supports only E2B SDK versions earlier than v2.25.0.

   pip install "e2b-code-interpreter==2.7.0" "e2b==2.24.0"

Step 3: Configure E2B_DOMAIN

E2B_DOMAIN is the domain configuration that the E2B SDK uses to connect to sandbox-manager. The client and add-on configurations must be identical.

For information about registering and resolving a domain, see Alibaba Cloud DNS.

# Set E2B_DOMAIN to match the domain parameter of the add-on
export E2B_DOMAIN=<YOUR_E2B_DOMAIN>
# Set E2B_API_KEY to match the adminApiKey parameter of the add-on
export E2B_API_KEY=<YOUR_API_KEY>

(Optional) Step 4: Install a certificate

To access sandbox-manager over HTTPS, install a TLS certificate. A certificate from a trusted CA is recommended. For details about applying for and configuring certificates, see the following topics:

• Method 1: cert-manager

• Method 2: Self-signed certificate

• Method 3: Public certificate

Verify that the Secret is created and that its type is correct (should be kubernetes.io/tls):

kubectl get secret sandbox-manager-tls -n sandbox-system

Step 5: Select an integration method to connect to the sandbox

Based on your network environment and requirements, select one of the following integration methods to connect to the sandbox.

In the following examples, code-interpreter is a placeholder. Replace it with the actual SandboxSet name that you created.

• Method 1: Access from outside the cluster using the Native Protocol: Recommended for production environments. Requires a wildcard domain and TLS certificate.

• Method 2: Access from outside the cluster using the Private Protocol (HTTPS): Requires only a single domain, which lowers the deployment barrier.

• Method 3: Use port forwarding for local debugging: Suitable for local development and debugging.

E2B API compatibility

Related documents

• Create an Agent Sandbox

• E2B Client