Agent Sandbox:Custom Domains

After a custom domain is bound, you can use:

• A control-plane domain to access Agent Sandbox Flash Edition APIs, for example https://api.example.com.

• A data-plane domain to access services inside a sandbox, for example https://{port}-{sandboxId}.example.com.

Using example.com as an example:

Limits

• When you bind a custom domain to Agent Sandbox Flash Edition, you must select the region where the sandbox is deployed.

• The control-plane domain currently supports only a single domain name prefixed with api., such as api.example.com.

• The data-plane domain is the wildcard domain obtained by removing the api. prefix from the control-plane domain, for example *.example.com.

• Only HTTPS is supported.

• You must upload a certificate that covers the data-plane wildcard domain, such as *.example.com. A single-domain certificate that only covers api.example.com is not sufficient.

• The private key must be an unencrypted RSA PEM key. If your private key is in the -----BEGIN PRIVATE KEY----- format, convert it to -----BEGIN RSA PRIVATE KEY----- first.

• Internationalized domain names are not supported.

• By default, one primary account can bind up to 5 Agent Sandbox Flash Edition custom domains. Contact support if you need a higher quota.

• Your custom domain must complete ICP filing or filing access as required by the console validation result.

Example of converting the private key format:

openssl rsa -in pkcs8.key -out pkcs1.key

1. Add a custom domain

1. Sign in to the Agent Sandbox console.

2. In the left-side navigation pane, choose Flash Edition > Domain Name Management.

3. Select the region where your Agent Sandbox Flash Edition instances are deployed.

4. Click Create a domain name.

5. On the Create a domain name page, enter the root domain, for example example.com. After the domain is created, the control-plane domain is api.example.com.

6. Follow the prompts to obtain the control-plane CNAME and data-plane CNAME for DNS configuration in the next step.

Important: The custom domain must use the same region as Agent Sandbox Flash Edition. Otherwise DNS resolution and certificate validation may fail.

2. Configure DNS resolution

Sign in to the Alibaba Cloud DNS console and point your custom domain to the CNAME records provided by Agent Sandbox Flash Edition.

Example: if your primary account ID is 119085698835**** and your Agent Sandbox Flash Edition region is China (Beijing), the data-plane CNAME can be configured as:

119085698835****.cn-beijing.sandbox.aliyuncs.com

After the configuration is complete, wait for DNS propagation before you submit or verify the domain. You can use the following commands to check the resolution result:

dig +short CNAME api.example.com
dig +short CNAME test.example.com

Here, test.example.com is used to verify whether the wildcard resolution for *.example.com has taken effect.

3. Configure an HTTPS certificate

Agent Sandbox Flash Edition custom domains always use HTTPS. Upload the certificate and private key when you add the domain.

Certificate requirements:

• The certificate must be valid.

• The certificate and private key must match.

• The certificate must cover the data-plane wildcard domain. For example, if the control-plane domain is api.example.com, the certificate must cover *.example.com.

4. Use a custom domain in the SDK

After the domain is added successfully, replace the API endpoint and data-plane base domain in the SDK with the custom domain that you bound.

TypeScript example:

import { Sandbox } from "e2b";

const sandbox = await Sandbox.create("code-interpreter-v1", {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: "https://api.example.com",
  domain: "example.com",
});

const host = sandbox.getHost(8000);
console.log(`https://${host}`);

Python example:

from e2b import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter-v1",
    api_key=os.environ["E2B_API_KEY"],
    api_url="https://api.example.com",
    domain="example.com",
)

host = sandbox.get_host(8000)
print(f"https://{host}")

If the sandbox ID is sandbox-id and the exposed port is 8000, the SDK returns an address in the following format:

https://8000-sandbox-id.example.com

5. Verify the custom domain

After the configuration is complete, verify it by following these steps:

1. Use the SDK or OpenAPI to create an Agent Sandbox Flash Edition instance.

2. Start an HTTP service inside the sandbox, for example on port 8000.

3. Call sandbox.getHost(8000) to get the access domain.

4. Use a browser or curl to access https://{port}-{sandboxId}.example.com.

Example:

curl -v https://8000-sandbox-id.example.com

If you receive a response from the service running inside the sandbox, the data-plane domain is working.

FAQ

Notes

• sandbox.getHost(port) returns only the host name. In most cases, you need to prepend https:// when accessing it.

• Custom domains are suitable for production or long-lived access scenarios. For temporary debugging, you can still use the default Agent Sandbox Flash Edition domain.

• Do not expose sensitive data, internal debugging endpoints, or long-lived credentials through unauthenticated port services.