DocsICP FilingConsole
Documentation
Home Page Agent Run Function Description Sandbox service AIO Sandbox

AIO Sandbox

Updated at:
Copy as MD
My Favorites

AIO Sandbox (All-In-One Sandbox) is a cloud-isolated runtime environment that integrates a headless browser (BrowserTool) and a code execution engine (Code Interpreter) in a single instance. Use AIO Sandbox to provide AI Agents with web automation, code execution, file processing, and interactive terminal access within a unified, secure session.

Use cases

  • AI Agent integration — Drive browser interactions and run code to process scraped data within the same session.

  • Automated testing — Run browser end-to-end (E2E) tests and background scripts together in a controlled container.

  • Data ingestion and processing — Scrape dynamically rendered pages with a browser, then parse, transform, and export the data inside the sandbox.

  • Content generation and archiving — Generate screenshots, PDFs, or screen recordings automatically, and store or download the results.

Key features

  • Fully managed — No need to manage browser clusters or code runtime dependencies. Alibaba Cloud handles infrastructure and scaling.

  • Serverless architecture — Pay-as-you-go billing with automatic scaling based on task load.

  • Native compatibility — Supports Puppeteer, Playwright, and other popular frameworks. Provides secure RESTful APIs.

Preparations

Configure permissions

The first time you use AIO Sandbox, log on to the AgentRun console (China) or the AgentRun console (International). Follow the on-screen instructions to create the service-linked role AliyunServiceRoleForAgentRun.

Obtain required information

Before you call AIO Sandbox APIs, obtain the following information:

  • Alibaba Cloud account ID — Retrieve this from your profile picture in the upper-right corner of the console.

  • Credential secret (API key) — Retrieve this from the Credential Management page in the console.

  • Data plane base URL — Use the base URL for the region where your sandbox runs:

    • China (Hangzhou): https://${Alibaba Cloud account ID}.agentrun-data.cn-hangzhou.aliyuncs.com

    • Singapore: https://${Alibaba Cloud account ID}.agentrun-data.ap-southeast-1.aliyuncs.com

Get started

Core concepts

  • Sandbox template — Defines the basic configuration of an instance, such as resource specifications.

  • Sandbox instance — The runtime environment where tasks are executed.

  • Lifecycle — A single instance can exist for a maximum of 6 hours.

  • Idle timeout — Set by sandboxIdleTimeoutInSeconds. If an instance is idle for longer than this value, its resources are released early.

Basic workflow

  1. Create a template: In the console, go to the Sandbox tab and choose Create Sandbox Template > AIO Sandbox. You can also create templates through the control plane API.

  2. Start an instance: Call the data plane API to create a sandbox instance based on the template.

  3. Execute code or control the browser: Connect to the CDP endpoint for browser automation, or use the Code Interpreter API to execute code. For working code examples, see Quick examples.

Quick examples

AIO Sandbox combines Code Interpreter and BrowserTool in a single instance. The sandbox comes pre-installed with puppeteer-core (Node.js) and playwright (Python). You can run the following code through the Code Interpreter to control the built-in browser.

Puppeteer (Node.js)

Puppeteer (Node.js) example:

const puppeteer = require('puppeteer-core');
async function controlBrowser() {
    // To enable recording, use 'ws://localhost:5000/ws/automation?recording=true'
    const browserWSEndpoint = 'ws://localhost:5000/ws/automation';
    console.log('Connecting to browser:', browserWSEndpoint);
    let browser;
    try {
        browser = await puppeteer.connect({
            browserWSEndpoint: browserWSEndpoint,
            timeout: 5000
        });
        console.log('Connection successful!');
        const page = await browser.newPage();
        await page.setViewport({ width: 1920, height: 1080 });
        console.log('Opening https://www.bing.com ...');
        await page.goto('https://www.bing.com', {
            waitUntil: 'networkidle2',
            timeout: 10000 
        });
        const title = await page.title();
        console.log('Page title:', title);
        console.log('Disconnected');
    } catch (error) {
        console.error('An error occurred:', error.message);
    } finally {
        if (browser) await browser.disconnect();
    }
}
(async () => {
    try {
        await controlBrowser();
        console.log("Script execution finished");
    } catch (err) {
        console.error("Uncaught top-level error:", err);
    }
})();

Playwright (Python)

Playwright (Python) example:

from playwright.sync_api import sync_playwright

def run():
    with sync_playwright() as playwright:
        chromium = playwright.chromium
        browser = chromium.connect_over_cdp("ws://localhost:5000/ws/automation")
        context = browser.contexts[0]
        page = context.pages[0]
        page.goto("https://www.example.com")
        print(page.title())
        browser.close()

run()

Submit the preceding code by using the /contexts/execute operation from Code Interpreter. The system automatically handles the browser interaction.

API overview

AIO Sandbox provides two API surfaces:

  • Control plane API — Manages sandbox templates. Access these operations through OpenAPI Explorer. You must create a template before you can start sandbox instances.

  • Data plane API — Manages sandbox instances at runtime (create, stop, and delete instances; execute code; control the browser). Call these endpoints directly through REST or an SDK.

To use AIO Sandbox, first create a template through the control plane, then use the data plane to start instances and run tasks.

Control plane API

Access OpenAPI Explorer

  1. Go to OpenAPI Explorer.

  2. In the top menu bar, click Select Cloud Product. In the search box, search for and select AgentRun.

  3. In the left-side navigation pane, find the API operations under Debug > Browser Sandbox to get started.

Template management

For more information, see the API documentation in the OpenAPI portal.

Data plane API reference

Use the data plane APIs to manage and operate sandbox instances. Before you can use these APIs, you must create a sandbox template by using the control plane API or the console.

Authentication

You must provide credentials to call the sandbox instance management APIs. Calls fail if credentials are not provided.

If you need to call these APIs without authentication, do not attach a credential when you create the template. This approach is not recommended.

These API operations are not yet available in OpenAPI Explorer. You can call the API endpoints directly or through an SDK.

Sandbox instance management

Create a sandbox instance

  • Request URI: POST ${BASEURL}/sandboxes

  • Request headers:

    X-Acs-Parent-Id: ${Alibaba Cloud account ID}

    X-API-KEY: Credential Secret

    Content-Type: application/json

  • Request body:

{
  "templateName": "string",
  "sandboxId": "string"
}
- `templateName` (string, required): The template name. The system uses this name to query the template ID.
- `sandboxId` (string, optional): A custom sandbox ID for end-to-end tracing. If not specified, the system automatically generates an ID in ULID format.

  • Response example:

{
  "sandboxId": "01JCED8Z9Y6XQVK8M2NRST5WXY",
  "templateId": "01JCED8Z9Y6XQVK8M2NRST5ABC",
  "templateName": "aio-sandbox",
  "templateType": "AllInOne",
  "status": "READY",
  "sandboxIdleTimeoutInSeconds": 3600,
  "createdAt": "2024-12-02T10:30:00Z",
  "lastUpdatedAt": "2024-12-02T10:30:15Z",
  "metadata": {
    "fcSessionDetails": {
      "sessionId": "1234567890abcdef",
      "sessionStatus": "Active",
      "sessionIdleTimeoutInSeconds": 3600,
      "functionName": "sandbox-function",
      "qualifier": "LATEST",
      "containerId": "container-123",
      "createdTime": "2024-12-02T10:30:00Z",
      "lastModifiedTime": "2024-12-02T10:30:15Z",
      "sessionAffinityType": "HEADER_FIELD"
    }
  }
}

Stop a sandbox instance

  • Request URI: POST ${BASEURL}/sandboxes/{sandboxId}/stop

  • Request headers:

    X-Acs-Parent-Id: ${Alibaba Cloud account ID}

    X-API-KEY: Credential Secret

  • Path parameters: sandboxId (string, required) — the sandbox ID.

  • Request body: None

  • Response example:

{
  "sandboxId": "01JCED8Z9Y6XQVK8M2NRST5WXY",
  "templateId": "01JCED8Z9Y6XQVK8M2NRST5ABC",
  "templateName": "aio-sandbox",
  "templateType": "AllInOne",
  "status": "TERMINATED",
  "sandboxIdleTimeoutInSeconds": 3600,
  "createdAt": "2024-12-02T10:30:00Z",
  "lastUpdatedAt": "2024-12-02T11:00:00Z",
  "endedAt": "2024-12-02T11:00:00Z"
}

When you stop a sandbox, the following behavior applies:

  • The Function Compute (FC) session is deleted and the database status is updated to TERMINATED.

  • The operation is idempotent. If the sandbox is already in the TERMINATED state, the call returns directly.

  • The endedAt timestamp is set.

Delete a sandbox instance

  • Request URI: DELETE ${BASEURL}/sandboxes/{sandboxId}

  • Request headers:

    X-Acs-Parent-Id: ${Alibaba Cloud account ID}

    X-API-KEY: Credential Secret

  • Path parameters: sandboxId (string, required) — the sandbox ID.

  • Request body: None

  • Response example:

{
  "sandboxId": "01JCED8Z9Y6XQVK8M2NRST5WXY",
  "templateId": "01JCED8Z9Y6XQVK8M2NRST5ABC",
  "templateName": "aio-sandbox",
  "templateType": "AllInOne",
  "status": "TERMINATED",
  "sandboxIdleTimeoutInSeconds": 3600,
  "createdAt": "2024-12-02T10:30:00Z",
  "lastUpdatedAt": "2024-12-02T11:30:00Z",
  "endedAt": "2024-12-02T11:00:00Z"
}

When you delete a sandbox, the system performs the following operations:

  • Checks whether the sandbox exists.

  • If the sandbox is in the READY state, calls StopSandbox to delete the FC session first.

  • Returns the status of the sandbox before deletion.

Instance status descriptions

Status

Description

CREATING

The instance is being created.

READY

The instance is ready to use.

TERMINATED

The instance is stopped (through the StopSandbox operation).

Health check

  • Request URI: GET ${BASEURL}/sandboxes/{sandboxId}/health

  • Request header: X-Acs-Parent-Id: ${Alibaba Cloud account ID}

  • Query parameters: None

  • Response example:

{
  "status": "ok"
}

Endpoints and protocols

BrowserTool endpoints

On the Details page of the AIO Sandbox, go to Debug and VNC. In the upper-right corner, click CDP or VNC to copy the endpoint address.

CDP automation endpoint

The CDP endpoint connects to Chromium's Chrome DevTools Protocol (CDP). It supports connect in Puppeteer and connectOverCDP in Playwright.

Endpoint format by region:

  • China (Hangzhou): wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxId}/ws/automation?tenantId={accountID}&Authorization={accessToken}

  • Singapore: wss://{accountID}.agentrun-data.ap-southeast-1.aliyuncs.com/sandboxes/{sandboxId}/ws/automation?tenantId={accountID}&Authorization={accessToken}

VNC real-time stream endpoint

The VNC endpoint lets you view the browser desktop in real time through a client such as noVNC. Use this endpoint for debugging and visual monitoring.

Endpoint format by region:

  • China (Hangzhou): wss://{accountID}.agentrun-data.cn-hangzhou.aliyuncs.com/sandboxes/{sandboxID}/ws/livestream?tenantId={accountID}&Authorization={accessToken}

  • Singapore: wss://{accountID}.agentrun-data.ap-southeast-1.aliyuncs.com/sandboxes/{sandboxID}/ws/livestream?tenantId={accountID}&Authorization={accessToken}

Recording management

AIO Sandbox provides VNC recording management through the following endpoints:

  • List recordings: GET /recordings/?page=&page_size= — Returns a list of recording files and their metadata.

  • Download a recording: GET /recordings/{filename} — Only .mkv files are supported (Content-Type: video/x-matroska). Streaming download is supported, which lets you download a file while it is being recorded.

  • Delete a recording: DELETE /recordings/{filename} — Use with caution. This operation cannot be undone.

For more information, see BrowserTool.

Code Interpreter

The Code Interpreter data plane API provides operations for code execution, file system management, and process management.

Base URL by region:

  • China (Hangzhou): https://${Alibaba Cloud account ID}.agentrun-data.cn-hangzhou.aliyuncs.com/

  • Singapore: https://${Alibaba Cloud account ID}.agentrun-data.ap-southeast-1.aliyuncs.com/

Key resources:

  • Create an execution context (language: python/javascript): POST /sandboxes/{sandboxId}/contexts

  • Execute code synchronously: POST /sandboxes/{sandboxId}/contexts/execute

  • File management: GET /sandboxes/{sandboxId}/filesystem, /filesystem/download, /filesystem/upload

  • Execute a command synchronously: POST /sandboxes/{sandboxId}/processes/cmd

  • WebSocket interactive terminal: GET /sandboxes/{sandboxId}/processes/tty?protocol=text

For more information, see Code Interpreter.

Limits and billing

  • Lifecycle — A single instance can exist for a maximum of 6 hours.

  • Billing mode — Pay-as-you-go serverless billing. For detailed billing rules, see Function Compute Billing overview.

  • Best practices:

    • Timely release — After a task is complete, call the stop operation or set a reasonable sandboxIdleTimeoutInSeconds.

    • Resource cleanup — Periodically delete unnecessary recording files from /recordings/.

    • Health check — Monitor instance availability by using GET /sandboxes/{sandboxId}/health.

Previous：Code InterpreterNext：Sandbox supports instance-level dynamic NAS mounting