Agent Sandbox:Build and manage custom templates with code

Select an image source

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen2-demo-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                disk_size=15360,
                # Deliver build and runtime logs to SLS in the same region.
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
                    generation=2,  # Required. 2 specifies a second-generation template.
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen2-acree-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                disk_size=15360,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image="<instance>-registry-vpc.cn-hangzhou.cr.aliyuncs.com/<namespace>/<image>:<tag>",
                    generation=2,
                    acr_instance_id="cri-xxxxxx",
                    registry_config=models.CreateTemplateRegistryConfig(
                        auth_config=models.CreateTemplateRegistryAuthConfig(
                            user_name="<username>",
                            password="<password>",
                        ),
                        network_config=models.CreateTemplateRegistryNetworkConfig(
                            vpc_id="<vpc-id>",
                            v_switch_id="<vsw-id>",
                            security_group_id="<sg-id>",
                        ),
                    ),
                ),
            ),
        )
    )
)

Configure the start command and ready command

The following example shows how the two commands work together for a pre-deployed HTTP service. During the build, the platform runs start_command as a background process to start the service. The platform then repeatedly runs ready_command until the command returns exit code 0, which means that the service is ready. Then, the platform creates a template snapshot for the sandbox that is still running. When you create a sandbox from this template, the service is already running and can be accessed immediately. The start command is not run again.

• Execution time: Both commands are executed only during the template build, and the results are fixed in the snapshot. They are not replayed when a sandbox is created.

• Format: Both commands are shell commands in string format, and both parameters are optional. If start_command is not specified, no extra start command is executed.

• Failure handling: If start_command exits prematurely, ready_command keeps failing, or the wait time exceeds 5 minutes, the template build fails. If ready_command is incorrectly specified, the typical symptom is a build timeout instead of a parameter error.

• Troubleshoot by using logs: Command output and failure causes are delivered to SLS by using log_config. View the logs in the corresponding Logstore.

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen2-service-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                disk_size=15360,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
                    generation=2,
                    # Run as a background process during the build.
                    start_command="python3 -m http.server 8000",
                    # Run repeatedly. An exit code of 0 once means the service is ready.
                    ready_command="curl -sf http://localhost:8000/ > /dev/null",
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

After the template is built and becomes ready, use the E2B SDK to create a sandbox and access the service:

from e2b import Sandbox

sandbox = Sandbox.create(
    template=template_id,
    timeout=600,
    # The SDK automatically reads the E2B_API_KEY, E2B_API_URL, and E2B_DOMAIN environment variables.
    api_url=f"https://api.{REGION}.e2b.fc.aliyuncs.com",
    domain=f"{REGION}.e2b.fc.aliyuncs.com",
)
try:
    host = sandbox.get_host(8000)
    print(f"https://{host}")
finally:
    sandbox.kill()

Select an image source

• Official public image: The address of an image for a first-generation template is in the fc-e2b-registry.<region>.cr.aliyuncs.com/runtime/<image-name>:<tag> format (the runtime-v2 prefix of a second-generation template is different). No credentials or network configurations are required. The platform uses the image directly and does not run the build injection.

• ACR EE image: The instance preparations, network constraints, and pull method are the same as those of the second-generation ACR EE image. Use the -vpc domain name in the image address. For an image in the same account, no credentials are required, and the platform pulls the image by using the temporary authorization of the instance.

• OCI-compliant image registry: any standard OCI registry reachable over the Internet or private in a VPC. Provide the registry credentials in registry_config.auth_config (user_name and password, which must have both the pull and push permissions). For a private registry in a VPC, also use registry_config.network_config to provide the three VPC parameters of the pull network (vpc_id, v_switch_id, and security_group_id).

Select a build method

When you build an unofficial image, a first-generation template uses build_config to control two build actions: copy (pushes the build output as the destination image) and envd_inject (injects the sandbox runtime dependencies).

If build_config is not specified, the build method is derived from the source image. An official public image is used directly without a build. Other images are built with injection. Note that copy and envd_inject must be enabled or disabled together. If only one of them is enabled, 400 is returned.

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen1-direct-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime/code-interpreter-v1:v0.0.53",
                    generation=1,
                ),
            ),
        )
    )
)

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen1-builder-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image="<instance>-registry-vpc.cn-hangzhou.cr.aliyuncs.com/<namespace>/<image>:<tag>",
                    generation=1,  # Required. 1 specifies a first-generation template.
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen1-oci-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image="registry.internal.example.com/<namespace>/<image>:<tag>",
                    generation=1,
                    registry_config=models.CreateTemplateRegistryConfig(
                        auth_config=models.CreateTemplateRegistryAuthConfig(
                            user_name="<username>",
                            password="<password>",
                        ),
                        network_config=models.CreateTemplateRegistryNetworkConfig(
                            vpc_id="<vpc-id>",
                            v_switch_id="<vsw-id>",
                            security_group_id="<sg-id>",
                        ),
                        cert_config=models.CreateTemplateRegistryCertConfig(
                            insecure=True,  # Specify this for a self-signed certificate
                        ),
                    ),
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

Query template information and build status

Use ListTemplates to query the templates of a Team by page, and use GetTemplate to query the configuration and build status of a single template. The status.state parameter has the following valid values: pending (waiting for the build), building (build in progress), updating (rebuilding after a configuration update), ready (ready to create sandboxes), and error (the build failed). The status.reason.message parameter provides the cause of a failure. Poll at an interval of 5 to 10 seconds.

Complete example that lists all templates by paging:

import os

from alibabacloud_sandbox20260820 import models
from alibabacloud_sandbox20260820.client import Client as SandboxClient
from alibabacloud_tea_openapi import models as open_api_models

REGION = "cn-hangzhou"
TEAM_ID = "<your-team-id>"

config = open_api_models.Config(
    access_key_id=os.environ["ALIBABA_CLOUD_ACCESS_KEY_ID"],
    access_key_secret=os.environ["ALIBABA_CLOUD_ACCESS_KEY_SECRET"],
    region_id=REGION,
    endpoint=f"sandbox.{REGION}.aliyuncs.com",
)
pop_client = SandboxClient(config)

next_token = None
while True:
    request = models.ListTemplatesRequest(team_id=TEAM_ID)
    if next_token:
        request.next_token = next_token
    response = pop_client.list_templates(request)
    for template in response.body.templates:
        print(template.template_id, template.name, template.status.state)
    next_token = response.body.next_token
    if not next_token:
        break

Create a sandbox from a built template

After the template enters the ready state, use the E2B SDK to create a sandbox and check the result:

from e2b import Sandbox

sandbox = Sandbox.create(
    template=template_id,
    timeout=600,
    api_url=f"https://api.{REGION}.e2b.fc.aliyuncs.com",
    domain=f"{REGION}.e2b.fc.aliyuncs.com",
)
try:
    result = sandbox.commands.run("printf hello")
    print(result.stdout)
finally:
    sandbox.kill()

Modify configurations and rebuild

Use UpdateTemplate to modify configuration items in place, such as the image, specification, and network configurations. After you submit the request, the platform automatically rebuilds the template, and the template returns to the updating state and restores the ready state after the build is complete:

pop_client.update_template(
    template_id,
    models.UpdateTemplateRequest(
        team_id=TEAM_ID,
        body=models.PublicUpdateTemplateInput(
            runtime_config=models.PublicUpdateTemplateRuntimeConfig(
                cpu=4,
                memory_size=4096,
            ),
        ),
    ),
)
state = wait_ready(template_id)
assert state == "ready"

• Pass only the configuration items that you want to modify. The items that you do not pass keep their original values.

Delete a template that is no longer used

pop_client.delete_template(
    template_id, models.DeleteTemplateRequest(team_id=TEAM_ID))

• A template can be deleted in any state, including the building state. The deletion terminates the build in progress.

Select a scenario

Note that the CIDR block of the VPC must use a private address range specified in RFC 1918 (10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16). The vSwitch must be located in a zone supported by Function Compute.

Scenario 1: Access the VPC and the Internet over a non-fixed egress IP address

Configure vpc_config, and keep internet_access enabled, which is the default:

runtime_config=models.CreateTemplateRuntimeConfig(
    cpu=2,
    memory_size=2048,
    disk_size=15360,
    internet_access=True,
    vpc_config=models.CreateTemplateVPCConfig(
        vpc_id="<vpc-id>",
        v_switch_ids=["<vsw-id>"],
        security_group_id="<sg-id>",
    ),
    log_config=models.CreateTemplateLogConfig(
        project="<sls-project>",
        logstore="<sls-logstore>",
    ),
    sandbox_config=models.CreateTemplateSandboxConfig(
        image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
        generation=2,
    ),
)

Verification: After the sandbox is created, access a resource in the VPC, such as an internal domain name or private IP address, and an Internet address, such as curl https://www.aliyun.com. Both are accessible. Scenario 1 (vpc_config configured and internet_access left enabled) does not provide a fixed Internet egress IP address.

Scenario 2: Access only the VPC but not the Internet

Configure vpc_config, and disable internet_access. Also make sure that the VPC itself provides no Internet egress:

runtime_config=models.CreateTemplateRuntimeConfig(
    cpu=2,
    memory_size=2048,
    disk_size=15360,
    internet_access=False,
    vpc_config=models.CreateTemplateVPCConfig(
        vpc_id="<vpc-id>",
        v_switch_ids=["<vsw-id>"],
        security_group_id="<sg-id>",
    ),
    log_config=models.CreateTemplateLogConfig(
        project="<sls-project>",
        logstore="<sls-logstore>",
    ),
    sandbox_config=models.CreateTemplateSandboxConfig(
        image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
        generation=2,
    ),
)

Verification: The sandbox can access resources in the VPC, but access to Internet addresses times out or is rejected.

Scenario 3: Access the VPC and the Internet over a fixed egress IP address

Configure vpc_config, and disable internet_access. In the VPC, provide an Internet NAT gateway, an EIP, and the corresponding routes and SNAT rules, so that Internet traffic egresses through the specified gateway.

1. VPC preparations: Configure an Internet NAT gateway for the VPC and associate an EIP with the gateway. For the related vSwitches, configure routes that point to the NAT gateway and add SNAT rules. Make sure that the traffic of the vSwitch that hosts the sandbox can reach the Internet over this egress.

2. Template configurations: the same parameters as Scenario 2 (internet_access=False + vpc_config).

Verification: Query the egress IP address in the sandbox, for example curl ifconfig.me. The EIP that you configured is returned.

The template build parameters of Scenario 2 and Scenario 3 are the same. The difference is whether the VPC provides an Internet egress. Therefore, after internet_access is disabled, you must still check the network configuration of the VPC to determine whether the sandbox can access the Internet.

Can a first-generation template configure a start command and a ready command?

No. If a first-generation template specifies start_command or ready_command, 400 InvalidParameter is returned. To fix a long-running process in a template, use a second-generation template.

Why do all build examples include log configurations?

log_config delivers the logs of the template build period and the sandbox running period to SLS in your account, which helps locate issues during build and runtime verification. During the build, the logs show the output of the start command and the ready command, and the cause of a build failure. During the run, the logs show the output of the processes inside the sandbox. The logs are viewed in the project and Logstore that you configure in the SLS console. Both must be in the same region as Agent Sandbox.

Why can the Internet still be accessed after internet_access is disabled?

internet_access controls only the Internet egress on the platform side. If the VPC that the template connects to already provides an Internet egress (NAT gateway + EIP + SNAT), the sandbox can still access the Internet over that egress. To completely isolate the sandbox from the Internet, check both the template parameters and the network configuration of the VPC.

How do I obtain a fixed Internet egress IP address?

Use the configuration of Scenario 3. On the template side, disable internet_access and configure vpc_config. On the VPC side, provide an Internet NAT gateway and an EIP, and configure the corresponding routes and SNAT rules. Then check whether the egress IP address in the sandbox is the EIP that you configured.

How do I troubleshoot image pull failures, build failures, or start failures?

1. Use GetTemplate to query status.reason.message, which provides the failure stage and the cause.

2. View detailed logs in the SLS Logstore configured by log_config.

3. Troubleshoot by failure stage:

   • Image pull failure: Check that the image address and tag are correct, the credentials have the pull permission, and the pull network is reachable (the VPC association of the ACR EE instance is active, and the outbound direction of the security group allows TCP port 443).

   • Build failure: Check that the image meets the image requirements, such as the linux/amd64 architecture, the /bin/bash path, and /etc/passwd being writable. For a first-generation template, check that the destination repository credentials have the push permission.

   • Start command or ready check failure (second generation): Check that start_command does not exit prematurely, and that ready_command probes the real readiness condition and passes within 5 minutes.