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 MicroVM 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 it exits with 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()

Query template information and build status

Use ListTemplates to query Team templates with pagination, 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). The remaining values are ready (ready to create sandboxes) and error (the build failed, and status.reason.message provides the cause). Polling at an interval of 5 to 10 seconds is recommended.

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. This method 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. For detailed instructions, see Configure a fixed public IP for a sandbox instance.

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, the network configuration of the VPC must still be checked to determine whether the sandbox can access the Internet.

Why do all build examples include log configurations?

log_config delivers logs from the template build and the sandbox runtime 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. View the logs 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, and SNAT rules), 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. Confirm that the VPC association of the ACR EE instance is active and that 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.

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