DocsICP FilingConsole
Documentation
Home Page Agent Run Function Description Data Link Access to AgentRun Custom domains (AgentRun)

Custom domains (AgentRun)

Updated at:
Copy as MD
My Favorites

The custom domain feature lets you access Agents, LLM agents, tools, or sandbox instances on AgentRun with a branded domain, such as api.example.com, instead of the default platform-provided address. AgentRun supports two types of custom domains for different resource-binding scenarios: standard and sandbox domains.

Domain type

Use case

Standard Domain Name

Binds resources such as Agents, LLM agents, and tools by using routing rules to map different paths to various backend services.

Sandbox Domain Name

Binds sandbox instances. Supports wildcard domain mode and single domain mode.

Prerequisites

Before you configure a custom domain, ensure you meet the following prerequisites:

  • Domain name: You have a domain that has completed ICP filing. This is required for services in the Chinese mainland.

  • RAM permissions: Your account must have write permissions for AgentRun, OSS, CDN, and Alibaba Cloud Certificates Service. For details, see Authorize RAM users to use AgentRun.

  • DNS service: You must be able to add a CNAME record at your domain's DNS provider.

  • SSL certificate (for HTTPS): You have either applied for a certificate through Alibaba Cloud Certificates Service or prepared a PEM-formatted certificate file and an RSA private key file.

Domain types

Standard domain

A Standard Domain Name binds resources such as Agents, LLM agents, and tools. A single standard domain lets you configure multiple routing rules to map different URL paths to different backend services. For example, you can route api.example.com/agent/* to an Agent instance and api.example.com/llm/* to an LLM agent service.

Sandbox domain

A Sandbox Domain Name is specifically designed for binding sandbox instances and supports the following two modes:

Mode

Domain format

Description

Wildcard Domain Pattern

*.sandbox.example.com

Each instance is accessed through a unique subdomain. This mode is ideal for scenarios that require domain-level isolation.

Single Domain Mode

sandbox.example.com

All instances share a single domain entry point. The target instance and port are specified by using header or query parameters. This mode is ideal for scenarios that require a unified entry point.

Create a standard domain

  1. Log on to the AgentRun console.

  2. In the left navigation pane, choose Custom Domain.

  3. Click Add Domain Name.

  4. For Domain Name Type, select Standard Domain Name.

  5. In the Domain Name field, enter your domain, for example, api.example.com.

    Note

    A standard domain cannot start with *..

  6. (Optional) In the Description field, enter a description for the domain.

  7. (Optional) Configure HTTPS. For more information, see Configure HTTPS.

  8. Click Save Changes.

  9. Using the information in the Domain CNAME Configuration section, add a CNAME record at your DNS provider to point the domain to the system-provided gateway address.

    Note

    Domain resolution typically takes 10 minutes to 24 hours to propagate. If your domain is hosted on Alibaba Cloud, you can configure the record in the Alibaba Cloud DNS Management console.

  10. Verify that the domain is active: On the Custom Domain page, click Details for the domain and confirm that its DNS status is displayed as Normal.

Create a sandbox domain

  1. Log on to the AgentRun console.

  2. In the left navigation pane, choose Custom Domain.

  3. Click Add Domain Name.

  4. For Domain Name Type, select Sandbox Domain Name.

  5. Select a Sandbox Domain Name Type:

    • Wildcard Domain Pattern: Enter a domain that starts with *., for example, *.sandbox.agentrun.cn. This lets you access different sandbox instances through subdomains.

    • Single Domain Mode: Enter a specific domain, for example, sandbox.example.com. Use header parameters to specify the sandbox instance and port.

  6. (Optional) Configure an HTTPS certificate.

  7. Click Save Changes.

  8. Add a CNAME record at your DNS provider to point the domain to the gateway address provided by the system.

  9. Verify that the domain is active: On the Custom Domain page, click Details for the target domain and confirm that the DNS status is displayed as Normal.

Configure HTTPS

When you create or edit a domain, you can configure an SSL certificate to enable HTTPS access.

  1. On the domain creation or editing page, find the HTTPS Configuration section.

  2. Choose a certificate configuration method:

    Method

    Description

    Manual Certificate

    Manually enter the certificate name, its content in PEM format, and the RSA private key.

    Alibaba Cloud Certificate

    Select an existing certificate from Alibaba Cloud Certificates Service.

  3. Click Save HTTPS Configuration.

  4. After saving, on the domain details page, confirm that the SSL certificate status is Normal. Then, navigate to https://{your_domain} in a browser to verify that no certificate warnings appear.

Important

Domains without an SSL certificate only support HTTP, which is not secure. We strongly recommend configuring an SSL certificate to enable encrypted HTTPS transmission.

Bind resources

Configure routing for a standard domain

Standard domains use routing rules to map different request paths to different backend resources.

  1. On the domain details page, choose Routing Configuration.

  2. Click Add Route.

  3. Configure the route parameters:

    Parameter

    Description

    Route Path

    The request path. Must start with a /. Examples: /, /*, /agent/*

    Request Method

    The supported HTTP methods. You can select multiple methods.

    Target Type

    Select the resource type to bind (currently only Agent is supported).

    Target Service

    Select the specific resource instance.

    Select Endpoint

    Select the endpoint of the resource.

  4. Click Save Changes.

You can also quickly bind a domain to a resource from its details page by using the Bind Custom Domain Name option. When binding, you can choose an existing domain or create a new one.

Resource binding for sandbox domains

A sandbox domain is ready to use immediately after creation and does not require additional route configuration to access sandbox instances. Specify the target instance by using a subdomain (wildcard domain mode) or header/query parameters (single domain mode).

Accessing services by domain

Standard domain access

After you configure routes for a standard domain, you can access the corresponding backend service by using the domain name and route path. For example:

https://api.example.com/agent/chat
https://api.example.com/llm/v1/chat/completions
https://api.example.com/tools/search

Requests are forwarded to the corresponding Agent, LLM agent, or tool service based on the routing rules.

Sandbox domain access

Wildcard domain mode

In wildcard domain mode, specify the access target by including the port number and instance ID in the subdomain.

Address format:

  • Specify port: {port}-{sandboxId}.sandbox.example.com

  • Default port: {sandboxId}.sandbox.example.com

Examples:

  • To access port 8080 of the sandbox instance XXXXXXXX, use the address 8080-XXXXXXXX.sandbox.example.com.

  • To access the default port of the sandbox instance XXXXXXXX, use the address XXXXXXXX.sandbox.example.com.

Single domain mode

In single domain mode, specify the target sandbox instance and port using header or query parameters.

Method 1: Pass parameters in headers (Recommended)

Required header parameters:

Header

Description

X-Sandbox-ID

The unique identifier of the sandbox instance.

X-Sandbox-Port

The port number of the sandbox instance.

Note

Both header parameters are required. If either one is missing, the request fails.

cURL request example:

curl -H "X-Sandbox-ID: your-sandbox-id" \
     -H "X-Sandbox-Port: 8080" \
     https://sandbox.example.com/your-path

Method 2: Pass parameters in the query string

Query parameter format: ?sandboxPort=8080&sandboxId=sb-prod-001

Example:

https://sandbox.example.com/your-path?sandboxId=your-sandbox-id&sandboxPort=8080
Note

Header parameters take precedence over query parameters. If you provide both, the system uses the values in the headers.

Manage domains

View domain details

On the Custom Domain page, click Details for a domain to view its basic information, CNAME address, DNS status, SSL certificate status, and bound resources.

Edit a domain

Click Edit for a domain to modify its HTTPS configuration and description.

Delete a domain

Click Delete for a domain. After confirmation, the domain and all its related configurations are permanently deleted.

Warning

Before deleting a domain, ensure that no traffic is directed to it.

API reference

You can also manage custom domains using the AgentRun APIs:

API

Description

CreateCustomDomain

Create a custom domain

ListCustomDomains

List custom domains

GetCustomDomain

Get a custom domain

UpdateCustomDomain

Update a custom domain

DeleteCustomDomain

Delete a custom domain

Related documentation

Previous：Access AgentRun HTTP APINext：Credential management