AIO Sandbox

https://sandbox.agent-infra.com/guide
Admin
AIO Sandbox is an all-in-one agent sandbox environment that combines Browser, Shell, File, MCP...
Tokens:43,453
Snippets:485
Trust Score:5.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Sandbox Response Data Example

Source: https://sandbox.agent-infra.com/guide/basic/sandbox

Sample output showing system environment details, installed runtimes, and available utilities.

```json
System Environment (v1.0.0.93):
- Linux 6.10.14-linuxkit (x86_64), with internet access
- User: e3f8da5a6253, with sudo privileges
- Home directory: /home/gem
- Timezone: Asia/Shanghai
- Occupied Ports: 8080,8079,8088,8091,8100,8101,8102,8200,8888,9222

Development Environment:
- Python 3.12.11 (commands: python3, pip3)
- Node.js v22.19.0 (commands: node, npm)
- Git git version 2.34.1 (command: git)
- GitHub CLI (command: gh)
- UV uv 0.8.9 (command: uv)

Available Tools:
- Text editors: vim, nano
- File operations: wget, curl, tar, zip, unzip, tree
- Network tools: ping, telnet, netcat, nmap
- Text processing: grep, sed, awk, jq
- System monitoring: htop, procps
- Image processing: imagemagick
- Audio/Video Downloader: yt-dlp
```

--------------------------------

### Start Docker container with recommended seccomp option

Source: https://sandbox.agent-infra.com/guide/start/faq

Use this command to ensure the container is started with the necessary seccomp configuration.

```bash
docker run --security-opt seccomp=unconfined --rm -it -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### Install Sandbox SDK

Source: https://sandbox.agent-infra.com/guide/start/quick-start

Install the required package for your development environment.

```python
pip install agent-sandbox
```

```ts
npm install @agent-infra/sandbox
```

--------------------------------

### Start agent via Shell API

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Triggers agent installation and execution from an external control plane by sending a command to the sandbox Shell API.

```bash
curl -X POST http://localhost:8080/v1/shell/exec \
  -H "Content-Type: application/json" \
  -d '{"command": "pip install my-agent && my-agent start"}'
```

--------------------------------

### Install extensions via lifecycle hook

Source: https://sandbox.agent-infra.com/guide/advanced/code-server-config

Use the RUN_HOOK_PRE_SERVICES environment variable to install VS Code extensions during container startup.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e RUN_HOOK_PRE_SERVICES="code-server --install-extension ms-python.python" \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### Start Display Recording

Source: https://sandbox.agent-infra.com/guide/basic/display

Initiates a desktop recording session and saves it to the specified file path.

```bash
curl -X POST "http://localhost:8080/v1/display/record" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "start",
    "save_path": "/home/gem/recordings/session.mp4"
  }'
```

--------------------------------

### Run OpenCode with Default Provider

Source: https://sandbox.agent-infra.com/guide/advanced/opencode

Starts the container with the default 'ark' provider using only an API key and model ID.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e OPENCODE_API_KEY="your-api-key" \
  -e OPENCODE_MODEL="your-model-id" \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### View Sandbox Environment Info

Source: https://sandbox.agent-infra.com/guide/start/quick-start

Displays the ASCII logo and environment details after starting the Docker container.

```bash
 █████╗ ██╗ ██████╗     ███████╗ █████╗ ███╗   ██╗██████╗ ██████╗  ██████╗ ██╗  ██╗
██╔══██╗██║██╔═══██╗    ██╔════╝██╔══██╗████╗  ██║██╔══██╗██╔══██╗██╔═══██╗╚██╗██╔╝
███████║██║██║   ██║    ███████╗███████║██╔██╗ ██║██║  ██║██████╔╝██║   ██║ ╚███╔╝
██╔══██║██║██║   ██║    ╚════██║██╔══██║██║╚██╗██║██║  ██║██╔══██╗██║   ██║ ██╔██╗
██║  ██║██║╚██████╔╝    ███████║██║  ██║██║ ╚████║██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗
╚═╝  ╚═╝╚═╝ ╚═════╝     ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝

🚀 AIO(All-in-One) Agent Sandbox Environment
📦 Image Version: 1.0.0.93
🌈 Dashboard: http://localhost:8080/index.html
🔌 MCP: http://localhost:8080/mcp
📚 Documentation: http://localhost:8080/v1/docs
```

--------------------------------

### Start AIO Sandbox with Docker

Source: https://sandbox.agent-infra.com/guide/start/cloud-deployment

Commands to run the sandbox container bound to the loopback interface for secure local access.

```bash
docker run \
  --security-opt seccomp=unconfined \
  --restart unless-stopped \
  --name aio-sandbox \
  -d \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/agent-infra/sandbox:latest
```

```bash
docker run \
  --security-opt seccomp=unconfined \
  --restart unless-stopped \
  --name aio-sandbox \
  -d \
  -p 127.0.0.1:8080:8080 \
  enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
```

--------------------------------

### Start Sandbox with JWT Public Key

Source: https://sandbox.agent-infra.com/guide/advanced/security

Launch the sandbox container with the public key provided as a base64-encoded environment variable.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e JWT_PUBLIC_KEY="$(base64 -w 0 public_key.pem)" \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### GET /v1/sandbox/packages/nodejs

Source: https://sandbox.agent-infra.com/guide/basic/sandbox

Retrieves a list of all installed Node.js packages in the sandbox environment, including their names and versions.

```APIDOC
## GET /v1/sandbox/packages/nodejs

### Description
Lists all installed Node.js packages in the sandbox environment.

### Method
GET

### Endpoint
http://127.0.0.1:8080/v1/sandbox/packages/nodejs

### Response
#### Success Response (200)
- **data** (array) - A list of objects containing package names and versions.
```

--------------------------------

### GET /v1/code/info

Source: https://sandbox.agent-infra.com/guide/basic/code

Retrieves information about the available runtime environments.

```APIDOC
## GET /v1/code/info

### Description
Retrieves information about the available runtime environments.

### Method
GET

### Endpoint
/v1/code/info
```

--------------------------------

### Implement Minimal Browser Terminal

Source: https://sandbox.agent-infra.com/guide/advanced/web-terminal

A complete example using xterm.js and WebSockets to connect to the sandbox shell.

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <link
      rel="stylesheet"
      href="http://localhost:8080/static/sandbox/xterm@5.3.0/css/xterm.css"
    />
    <style>
      html,
      body,
      #terminal {
        width: 100%;
        height: 100%;
        margin: 0;
      }
    </style>
  </head>
  <body>
    <div id="terminal"></div>

    <script src="http://localhost:8080/static/sandbox/xterm@5.3.0/lib/xterm.js"></script>
    <script src="http://localhost:8080/static/sandbox/xterm-addon-fit@0.8.0/lib/xterm-addon-fit.js"></script>
    <script>
      const term = new Terminal({ cursorBlink: true, convertEol: true });
      const fitAddon = new FitAddon.FitAddon();
      term.loadAddon(fitAddon);
      term.open(document.getElementById("terminal"));
      fitAddon.fit();

      const ws = new WebSocket("ws://localhost:8080/v1/shell/ws");

      ws.addEventListener("open", () => {
        ws.send(JSON.stringify({
          type: "resize",
          data: { cols: term.cols, rows: term.rows },
        }));
      });

      term.onData((data) => {
        ws.send(JSON.stringify({ type: "input", data }));
      });

      ws.addEventListener("message", (event) => {
        const message = JSON.parse(event.data);

        if (message.type === "output") {
          term.write(message.data);
        }

        if (message.type === "ping") {
          ws.send(JSON.stringify({
            type: "pong",
            data: { timestamp: message.timestamp ?? message.data },
          }));
        }
      });

      window.addEventListener("resize", () => {
        fitAddon.fit();
        ws.send(JSON.stringify({
          type: "resize",
          data: { cols: term.cols, rows: term.rows },
        }));
      });
    </script>
  </body>
</html>
```

--------------------------------

### Start agent directly inside container

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Recommended method for running the agent from within the sandbox shell or Web Terminal.

```bash
python -m pip install my-agent
my-agent start
```

--------------------------------

### List Node.js Packages

Source: https://sandbox.agent-infra.com/guide/basic/sandbox

Retrieves a list of installed Node.js packages and their versions.

```python
nodejs_packages = client.sandbox.nodejs_packages()
print(nodejs_packages.data)
```

```bash
curl -X 'GET' \
  'http://127.0.0.1:8080/v1/sandbox/packages/nodejs' \
  -H 'accept: application/json'
```

--------------------------------

### Orchestrate multiple sandboxes with Docker

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Starts multiple sandbox containers on different host ports for parallel task isolation.

```bash
docker run --rm -d --name sandbox-react -p 127.0.0.1:8080:8080 \
  ghcr.io/agent-infra/sandbox:latest

docker run --rm -d --name sandbox-vue -p 127.0.0.1:8081:8080 \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### GET /v1/shell/ws

Source: https://sandbox.agent-infra.com/guide/basic/shell

Establishes a WebSocket connection for interactive terminal access.

```APIDOC
## GET /v1/shell/ws

### Description
Establishes a WebSocket connection for interactive terminal access. Supports input events and terminal resizing.

### Method
GET

### Endpoint
/v1/shell/ws
```

--------------------------------

### List Python Packages

Source: https://sandbox.agent-infra.com/guide/basic/sandbox

Retrieves a list of installed Python packages and their versions.

```python
python_packages = client.sandbox.python_packages()
print(python_packages.data) # [{ "name": "requests", "version": "2.32.5" }]
```

```bash
curl -X 'GET' \
  'http://127.0.0.1:8080/v1/sandbox/packages/python' \
  -H 'accept: application/json'
```

--------------------------------

### GET /v1/sandbox

Source: https://sandbox.agent-infra.com/guide/basic/sandbox

Retrieves sandbox environment information including system configuration, available resources, and home directory path.

```APIDOC
## GET /v1/sandbox

### Description
Retrieves sandbox environment information including system configuration and available resources.

### Method
GET

### Endpoint
/v1/sandbox

### Response
#### Success Response (200)
- **success** (boolean) - Indicates operation success
- **message** (string) - Operation result message
- **data** (object) - Sandbox environment data
- **home_dir** (string) - Home directory path in the sandbox
```

--------------------------------

### GET /v1/browser/info

Source: https://sandbox.agent-infra.com/guide/advanced/browser-config

Retrieves information about the current browser instance.

```APIDOC
## GET /v1/browser/info

### Description
Retrieves information about the current browser instance.

### Method
GET

### Endpoint
/v1/browser/info
```

--------------------------------

### Handle Long-Running Commands via API

Source: https://sandbox.agent-infra.com/guide/basic/bash

Demonstrates starting a long-running command and polling for incremental output using the REST API.

```bash
# 1. Start a command. If it is not done within 1 second, it returns running.
curl -X POST "http://localhost:8080/v1/bash/exec" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "sleep 3; echo done",
    "timeout": 1,
    "hard_timeout": 30
  }'
```

```bash
# 2. Continue reading with the returned session_id, offset, and stderr_offset.
curl -X POST "http://localhost:8080/v1/bash/output" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "SESSION_ID",
    "offset": 0,
    "stderr_offset": 0,
    "wait": true,
    "wait_timeout": 10
  }'
```

--------------------------------

### Handle Execution Errors

Source: https://sandbox.agent-infra.com/guide/basic/error-handling

Example of a JSON response where the sandbox request succeeded, but the executed command returned an error.

```json
{
  "success": true,
  "data": {
    "status": "finished",
    "exit_code": 1,
    "stdout": "",
    "stderr": "command not found"
  }
}
```

--------------------------------

### Handle File Not Found Error

Source: https://sandbox.agent-infra.com/guide/basic/file

Example of a standard error response returned when a file operation fails due to a missing file.

```json
{
  "success": false,
  "message": "Failed to read file: [Errno 2] No such file or directory: '/tmp/missing.txt'",
  "data": {
    "path": "/tmp/missing.txt",
    "operation": "read",
    "message": "Failed to read file: [Errno 2] No such file or directory: '/tmp/missing.txt'",
    "error_type": "not_found",
    "retryable": false,
    "errno": 2,
    "errno_name": "ENOENT",
    "exception_type": "FileNotFoundError"
  }
}
```

--------------------------------

### Log MCP Tool Calls

Source: https://sandbox.agent-infra.com/guide/basic/mcp

Wraps tool execution in a logging block to track start times, durations, and potential errors.

```python
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def logged_mcp_call(tool_name, **kwargs):
    """MCP call with comprehensive logging"""
    start_time = time.time()

    logger.info(f"MCP call starting: {tool_name} with args {kwargs}")

    try:
        result = await call_tool(tool_name, **kwargs)
        duration = time.time() - start_time

        logger.info(f"MCP call completed: {tool_name} in {duration:.2f}s")
        return result

    except Exception as e:
        duration = time.time() - start_time
        logger.error(f"MCP call failed: {tool_name} in {duration:.2f}s - {str(e)}")
        raise
```

--------------------------------

### GET /v1/sandbox/packages/python

Source: https://sandbox.agent-infra.com/guide/basic/sandbox

Retrieves a list of all installed Python packages in the sandbox environment, including their names and versions.

```APIDOC
## GET /v1/sandbox/packages/python

### Description
Lists all installed Python packages in the sandbox environment.

### Method
GET

### Endpoint
http://127.0.0.1:8080/v1/sandbox/packages/python

### Response
#### Success Response (200)
- **data** (array) - A list of objects containing package names and versions.
```

--------------------------------

### Initialize New Project

Source: https://sandbox.agent-infra.com/guide/basic/code-server

Commands to create a project directory and initialize a new Node.js and Git repository.

```bash
# Create project structure
mkdir -p /home/gem/projects/new-app
cd /home/gem/projects/new-app

# Initialize project
npm init -y
git init

# Open in Code Server
# Navigate to http://localhost:8080/code-server/
# Open folder: /home/gem/projects/new-app
```

--------------------------------

### Configure Sandbox Client

Source: https://sandbox.agent-infra.com/guide/start/quick-start

Initialize the client by providing the base URL of the running sandbox instance.

```python
from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")
```

--------------------------------

### Connect SDK to the sandbox

Source: https://sandbox.agent-infra.com/guide/start/faq

Initialize the SDK client with the correct base URL to establish a connection.

```python
from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")
print(client.sandbox.get_context())
```

--------------------------------

### GET /v1/file/download

Source: https://sandbox.agent-infra.com/guide/basic/file

Downloads a file as a binary stream.

```APIDOC
## GET /v1/file/download

### Description
Downloads a file from the sandbox as a binary stream. Unlike other file APIs, this returns standard HTTP errors on failure.

### Method
GET

### Endpoint
/v1/file/download
```

--------------------------------

### GET /v1/bash/sessions

Source: https://sandbox.agent-infra.com/guide/basic/bash

Lists all active bash sessions.

```APIDOC
## GET /v1/bash/sessions

### Description
Retrieves a list of all currently active bash sessions.

### Method
GET

### Endpoint
/v1/bash/sessions
```

--------------------------------

### Configure Startup Hooks via Docker Environment Variables

Source: https://sandbox.agent-infra.com/guide/advanced/lifecycle

Use environment variables to inject startup commands during container initialization.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e RUN_HOOK_PRE_SERVICES="python -m pip install requests" \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### GET /v1/jupyter/sessions

Source: https://sandbox.agent-infra.com/guide/basic/jupyter

Lists all active Jupyter sessions.

```APIDOC
## GET /v1/jupyter/sessions

### Description
Returns a list of all currently active Jupyter sessions.

### Method
GET

### Endpoint
/v1/jupyter/sessions
```

--------------------------------

### GET /v1/nodejs/sessions

Source: https://sandbox.agent-infra.com/guide/basic/nodejs

Lists all active Node.js sessions.

```APIDOC
## GET /v1/nodejs/sessions

### Description
Retrieves a list of all currently active Node.js sessions.

### Method
GET

### Endpoint
/v1/nodejs/sessions
```

--------------------------------

### Recommended Workspace Structure

Source: https://sandbox.agent-infra.com/guide/basic/code-server

Standard directory layout for organizing projects and configurations within the sandbox.

```text
/home/gem/
├── projects/           # Your development projects
├── Downloads/          # Browser downloads
├── .config/           # Tool configurations
└── workspace/         # Current working directory
```

--------------------------------

### GET /v1/proxy/mappings

Source: https://sandbox.agent-infra.com/guide/advanced/proxy-network

Lists all current proxy mappings.

```APIDOC
## GET /v1/proxy/mappings

### Description
Lists all current proxy mappings.

### Method
GET

### Endpoint
/v1/proxy/mappings
```

--------------------------------

### GET /v1/browser/screenshot

Source: https://sandbox.agent-infra.com/guide/basic/browser

Captures a screenshot of the current browser state.

```APIDOC
## GET /v1/browser/screenshot

### Description
Captures a visual screenshot of the browser and returns it as an image/png.

### Method
GET

### Endpoint
/v1/browser/screenshot

### Response
#### Success Response (200)
- **image** (image/png) - The captured browser screenshot.
```

--------------------------------

### GET /v1/skills/metadatas

Source: https://sandbox.agent-infra.com/guide/basic/skills

Retrieves a list of all registered skills and their metadata.

```APIDOC
## GET /v1/skills/metadatas

### Description
Lists all skills currently registered in the system.

### Method
GET

### Endpoint
/v1/skills/metadatas
```

--------------------------------

### Manage multiple sandboxes with Python

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Demonstrates iterating over a dictionary of sandbox clients to perform operations across different environments.

```python
from agent_sandbox import Sandbox

sandboxes = {
    "react": Sandbox(base_url="http://localhost:8080"),
    "vue": Sandbox(base_url="http://localhost:8081"),
}

for name, sandbox in sandboxes.items():
    sandbox.file.write_file(
        file="/home/gem/workspace/variant.txt",
        content=f"variant={name}\n",
    )
    result = sandbox.shell.exec_command(
        command="cat /home/gem/workspace/variant.txt",
    )
    print(name, result.data.output)
```

--------------------------------

### GET /v1/jupyter/info

Source: https://sandbox.agent-infra.com/guide/basic/jupyter

Retrieves information about the current Jupyter kernel.

```APIDOC
## GET /v1/jupyter/info

### Description
Retrieves status and information regarding the active Jupyter kernel.

### Method
GET

### Endpoint
/v1/jupyter/info
```

--------------------------------

### Run Codex with Custom Configuration

Source: https://sandbox.agent-infra.com/guide/advanced/codex

Launch the sandbox container using full custom TOML configuration and a model catalog JSON file.

```bash
export CODEX_CONFIG_TOML='model = "custom-model"
model_provider = "custom"
model_catalog_json = "model-catalog.json"
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.custom]
name = "custom"
base_url = "https://example.com/api/v3"
wire_api = "responses"
env_key = "CUSTOM_API_KEY"
'

export CODEX_MODEL_CATALOG_JSON='{"models":[{"id":"custom-model","name":"Custom Model"}]}'

docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e CUSTOM_API_KEY="your-api-key" \
  -e CODEX_CONFIG_TOML \
  -e CODEX_MODEL_CATALOG_JSON \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### GET /v1/nodejs/info

Source: https://sandbox.agent-infra.com/guide/basic/nodejs

Retrieves information about the Node.js runtime environment.

```APIDOC
## GET /v1/nodejs/info

### Description
Returns information regarding the current Node.js runtime environment.

### Method
GET

### Endpoint
/v1/nodejs/info
```

--------------------------------

### Run OpenCode with Full JSON Configuration

Source: https://sandbox.agent-infra.com/guide/advanced/opencode

Provides a complete configuration object via the OPENCODE_JSON environment variable for advanced customization.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e OPENCODE_JSON='{"model":"my-provider/my-model","provider":{"my-provider":{"npm":"@ai-sdk/openai-compatible","options":{"baseURL":"https://example.com/v1","apiKey":"your-api-key"},"models":{"my-model":{}}}}}' \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### GET /v1/sandbox/hooks

Source: https://sandbox.agent-infra.com/guide/advanced/lifecycle

Lists all registered hooks for a specific event.

```APIDOC
## GET /v1/sandbox/hooks

### Description
Retrieves a list of hooks registered for a specific event.

### Method
GET

### Endpoint
/v1/sandbox/hooks

### Query Parameters
- **event** (string) - Required - The event type to filter by (e.g., "shutdown")
```

--------------------------------

### Integrate with browser-use Library

Source: https://sandbox.agent-infra.com/guide/basic/browser

Configure a browser session using the sandbox CDP URL and the browser-use library.

```python
import requests
from agent_sandbox import Sandbox
from browser_use.browser.browser import BrowserSession, BrowserProfile

# Get CDP URL
client = Sandbox(base_url="http://localhost:8080")
cdp_url = client.browser.get_info().cdp_url

# Configure browser profile
profile = {
	"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
	"ignore_https_errors": True,
	"viewport": {"width": 1920, "height": 1080},
}

# Create session
browser_session = BrowserSession(
	browser_profile=BrowserProfile(**profile),
	cdp_url=cdp_url
)

await browser_session.start()
page = await browser_session.browser_context.new_page()
await page.goto("https://example.com")
```

--------------------------------

### GET /v1/proxy/upstream

Source: https://sandbox.agent-infra.com/guide/advanced/proxy-network

Retrieves the current upstream proxy configuration.

```APIDOC
## GET /v1/proxy/upstream

### Description
Retrieves the current upstream proxy configuration.

### Method
GET

### Endpoint
/v1/proxy/upstream
```

--------------------------------

### Execute shell and file operations with Python SDK

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Initializes the sandbox client and performs basic shell execution and file writing operations.

```python
from agent_sandbox import Sandbox

sandbox = Sandbox(base_url="http://localhost:8080")

result = sandbox.shell.exec_command(command="pwd && ls -la")
print(result.data.output)

sandbox.file.write_file(
    file="/home/gem/workspace/task.txt",
    content="Build a small demo app",
)
```

--------------------------------

### GET /v1/proxy/health

Source: https://sandbox.agent-infra.com/guide/advanced/proxy-network

Checks the health status of the proxy service.

```APIDOC
## GET /v1/proxy/health

### Description
Checks the health status of the proxy service.

### Method
GET

### Endpoint
/v1/proxy/health
```

--------------------------------

### Run Codex with Responses-compatible Endpoint

Source: https://sandbox.agent-infra.com/guide/advanced/codex

Launch the sandbox container using a custom API key, model ID, and base URL.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e CODEX_API_KEY="your-api-key" \
  -e CODEX_MODEL="your-model-id" \
  -e CODEX_BASE_URL="https://example.com/api/v3" \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### GET /json/version

Source: https://sandbox.agent-infra.com/guide/basic/browser

Retrieves the browser version and the WebSocket debugger URL.

```APIDOC
## GET /json/version

### Description
Returns the browser version information and the WebSocket debugger URL.

### Method
GET

### Endpoint
http://localhost:8080/json/version

### Response
#### Success Response (200)
- **webSocketDebuggerUrl** (string) - The WebSocket URL for debugging the browser instance.
```

--------------------------------

### Run AIO Sandbox with China Mirror

Source: https://sandbox.agent-infra.com/guide/start/quick-start

Use this command for faster image downloads if located in Mainland China.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
```

--------------------------------

### Run sandbox with runtime credentials

Source: https://sandbox.agent-infra.com/guide/advanced/git-config

Use runtime credentials via environment variables to access private repositories securely.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e GIT_ASKPASS=/home/gem/git-askpass.sh \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### Interact with shared files via API and shell

Source: https://sandbox.agent-infra.com/guide/basic/file

Demonstrates creating a file via HTTP POST and accessing it through shell commands or code-server.

```bash
# Create a file through the API
curl -X POST http://localhost:8080/v1/file/write \
  -H "Content-Type: application/json" \
  -d '{"file": "/home/gem/workspace/shared.txt", "content": "Shared content"}'

# Read it from a shell
# ws://localhost:8080/v1/shell/ws
# > cat /home/gem/workspace/shared.txt
# Shared content

# Edit it in code-server
# http://localhost:8080/code-server/
# Open /home/gem/workspace/shared.txt
```

--------------------------------

### GET /v1/skills/{name}/content

Source: https://sandbox.agent-infra.com/guide/basic/skills

Reads the content of a specific registered skill.

```APIDOC
## GET /v1/skills/{name}/content

### Description
Retrieves the content of the specified skill.

### Method
GET

### Endpoint
/v1/skills/{name}/content

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the skill to read.
```

--------------------------------

### Manage file permissions with sudo

Source: https://sandbox.agent-infra.com/guide/basic/file

Demonstrates accessing protected system paths by enabling the sudo flag.

```python
result = api.read_file("/home/gem/workspace/file.txt")

result = api.read_file("/etc/nginx/nginx.conf", sudo=True)

api.write_file(
    "/etc/cron.d/example",
    "0 2 * * * root /home/gem/workspace/backup.sh\n",
    sudo=True,
)
```

--------------------------------

### GET /v1/file/watch/{watcher_id}/events

Source: https://sandbox.agent-infra.com/guide/basic/file

Streams file events via Server-Sent Events.

```APIDOC
## GET /v1/file/watch/{watcher_id}/events

### Description
Opens an SSE stream to receive real-time file change events.

### Method
GET

### Endpoint
/v1/file/watch/{watcher_id}/events

### Parameters
#### Path Parameters
- **watcher_id** (string) - Required - The ID of the watcher.
```

--------------------------------

### Run Codex with Official OpenAI API

Source: https://sandbox.agent-infra.com/guide/advanced/codex

Launch the sandbox container using an official OpenAI API key.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e OPENAI_API_KEY="sk-xxx" \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### GET /v1/browser/info

Source: https://sandbox.agent-infra.com/guide/basic/browser

Retrieves the browser information including the CDP URL for remote debugging.

```APIDOC
## GET /v1/browser/info

### Description
Retrieves the browser information, specifically the CDP URL required for instrumenting the browser.

### Method
GET

### Endpoint
http://127.0.0.1:8080/v1/browser/info

### Response
#### Success Response (200)
- **data.cdp_url** (string) - The WebSocket URL for the Chrome DevTools Protocol.
```

--------------------------------

### Configure Browser Language

Source: https://sandbox.agent-infra.com/guide/advanced/browser-config

Sets the browser language and Accept-Language header via environment variable during container startup.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e BROWSER_LANG=en-US \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### Access Service with JWT

Source: https://sandbox.agent-infra.com/guide/basic/authentication

Performs an authenticated GET request using the Authorization header.

```bash
curl --silent --show-error -X GET "http://localhost:8080/cdp/json/version" \
     -H "Authorization: Bearer ${jwt}"
```

--------------------------------

### Bake repository into a Docker image

Source: https://sandbox.agent-infra.com/guide/advanced/git-config

Include a repository in a custom image to improve startup performance.

```dockerfile
FROM ghcr.io/agent-infra/sandbox:latest
RUN git clone --depth 1 https://github.com/user/repo.git /home/gem/repo
```

--------------------------------

### API response structure

Source: https://sandbox.agent-infra.com/guide/basic/file

Example of a successful JSON response returned by the file read endpoint.

```json
{
  "success": true,
  "message": "File read successfully",
  "data": {
    "content": "export PATH=...",
    "line_count": 10,
    "file": "/home/gem/.bashrc"
  }
}
```

--------------------------------

### Set Browser Homepage

Source: https://sandbox.agent-infra.com/guide/advanced/browser-config

Defines the default page opened upon browser startup.

```bash
-e HOMEPAGE=https://example.com
```

--------------------------------

### POST /v1/bash/sessions/create

Source: https://sandbox.agent-infra.com/guide/basic/bash

Creates a new bash session.

```APIDOC
## POST /v1/bash/sessions/create

### Description
Initializes a new bash session environment.

### Method
POST

### Endpoint
/v1/bash/sessions/create
```

--------------------------------

### POST /v1/display/record

Source: https://sandbox.agent-infra.com/guide/basic/display

Controls the desktop recording process by sending an action command.

```APIDOC
## POST /v1/display/record

### Description
Controls the desktop recording state. Use this endpoint to start, stop, or check the status of a recording session.

### Method
POST

### Endpoint
/v1/display/record

### Request Body
- **action** (string) - Required - The command to execute: "start", "status", or "stop".
- **save_path** (string) - Optional - The file path where the MP4 recording will be saved (required for "start" action).

### Request Example
{
  "action": "start",
  "save_path": "/home/gem/recordings/session.mp4"
}
```

--------------------------------

### Run agent script on Docker startup

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Mounts a local agent script into the container and executes it automatically after the sandbox service initializes.

```bash
docker run --rm -it -p 127.0.0.1:8080:8080 \
  -v "$PWD/agent.py:/home/gem/agent.py" \
  ghcr.io/agent-infra/sandbox:latest \
  bash -lc "/entrypoint.sh & sleep 5 && python /home/gem/agent.py"
```

--------------------------------

### Register Skills via API

Source: https://sandbox.agent-infra.com/guide/basic/skills

Endpoints for registering existing local directories or uploading new skill archives.

```bash
curl -X POST "http://localhost:8080/v1/skills/register" \
  -F "path=/home/gem/skills/report-writer"
```

```bash
curl -X POST "http://localhost:8080/v1/skills/register" \
  -F "file=@report-writer.zip" \
  -F "path=/home/gem/skills" \
  -F "name=report-writer"
```

--------------------------------

### Handle Tool-Level Failures

Source: https://sandbox.agent-infra.com/guide/basic/error-handling

Example of a JSON response indicating a tool failure despite a successful HTTP request.

```json
{
  "success": false,
  "message": "command failed",
  "data": null
}
```

--------------------------------

### Run AIO Sandbox with Docker

Source: https://sandbox.agent-infra.com/guide/start/quick-start

Standard command to pull and run the latest version of the sandbox.

```bash
# Pull and run the latest version
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### Execute local commands and localhost API calls

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Demonstrates using subprocess for local commands and requests to interact with sandbox REST services.

```python
import subprocess

import requests

result = subprocess.run(
    ["python", "--version"],
    capture_output=True,
    text=True,
    check=True,
)
print(result.stdout)

response = requests.post(
    "http://127.0.0.1:8080/v1/file/write",
    json={
        "file": "/home/gem/workspace/agent-note.txt",
        "content": "created from an in-sandbox agent\n",
    },
    timeout=10,
)
response.raise_for_status()
```

--------------------------------

### Retrieve Sandbox Context

Source: https://sandbox.agent-infra.com/guide/basic/sandbox

Fetches environment information including system configuration and available resources.

```python
ctx = client.sandbox.get_context()
print(ctx)
```

```bash
curl -X 'GET' \
  'http://127.0.0.1:8080/v1/sandbox' \
  -H 'accept: application/json'
```

--------------------------------

### List Download Directory

Source: https://sandbox.agent-infra.com/guide/advanced/browser-downloads

Use the file API to list the contents of the default download directory.

```text
/home/gem/Downloads
```

```bash
curl -X POST "http://localhost:8080/v1/file/list" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/gem/Downloads"}'
```

--------------------------------

### Construct VNC URL with Ticket

Source: https://sandbox.agent-infra.com/guide/basic/authentication

Builds a URL for VNC access using a short-lived ticket.

```bash
# Bash script simulating client URL construction
vnc_url="http://localhost:8080/vnc/index.html?ticket=${ticket}&path=websockify%3Fticket%3D${ticket}"

echo "Final URL built by client: ${vnc_url}"

# Simulate access (should be done in browser)
# curl -I "${vnc_url}"
```

--------------------------------

### GET /v1/jupyter/info

Source: https://sandbox.agent-infra.com/guide/basic/code-execution

Retrieves information about the Jupyter environment, including available kernels, default kernel, session timeout, and maximum sessions.

```APIDOC
## GET /v1/jupyter/info

### Description
Retrieves information about the Jupyter environment, including available kernels, default kernel, session timeout, and maximum sessions.

### Method
GET

### Endpoint
/v1/jupyter/info

### Response
#### Success Response (200)
- **available_kernels** (list) - List of available kernel names
- **default_kernel** (string) - The default kernel name
- **session_timeout_seconds** (integer) - Session timeout in seconds
- **max_sessions** (integer) - Maximum allowed sessions
```

--------------------------------

### Clone a public repository

Source: https://sandbox.agent-infra.com/guide/advanced/git-config

Use this command to clone a public repository directly into the sandbox file system.

```bash
git clone https://github.com/user/repo.git /home/gem/repo
```

--------------------------------

### Execute Bash Commands via SDK

Source: https://sandbox.agent-infra.com/guide/basic/bash

Demonstrates executing a bash command and retrieving stdout, stderr, and exit codes using the Python and TypeScript SDKs.

```python
from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")

result = client.bash.exec(
    command='printf "out\n" && printf "err\n" >&2',
    timeout=30,
    hard_timeout=120,
).data

print(result.stdout)
print(result.stderr)
print(result.exit_code)
```

```typescript
import { SandboxClient } from "@agent-infra/sandbox";

const client = new SandboxClient({ baseUrl: "http://localhost:8080" });

const response = await client.bash.exec({
  command: 'printf "out\n" && printf "err\n" >&2',
  timeout: 30,
  hard_timeout: 120,
});

if (!response.ok) {
  throw new Error("Bash exec failed");
}

console.log(response.body.data?.stdout);
console.log(response.body.data?.stderr);
console.log(response.body.data?.exit_code);
```

--------------------------------

### POST /v1/browser/restart

Source: https://sandbox.agent-infra.com/guide/advanced/browser-config

Restarts the browser instance.

```APIDOC
## POST /v1/browser/restart

### Description
Restarts the browser instance.

### Method
POST

### Endpoint
/v1/browser/restart
```

--------------------------------

### Kubernetes Deployment and Service

Source: https://sandbox.agent-infra.com/guide/start/cloud-deployment

YAML configuration for deploying the sandbox as a private ClusterIP service.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: aio-sandbox
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aio-sandbox
  template:
    metadata:
      labels:
        app: aio-sandbox
    spec:
      containers:
        - name: aio-sandbox
          image: ghcr.io/agent-infra/sandbox:latest
          ports:
            - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: aio-sandbox
spec:
  selector:
    app: aio-sandbox
  ports:
    - name: http
      port: 80
      targetPort: 8080
  type: ClusterIP
```

--------------------------------

### Access VNC Interface

Source: https://sandbox.agent-infra.com/guide/basic/browser

Use this URL to access the VNC interface or embed it in an iframe.

```bash
http://localhost:8080/vnc/index.html?autoconnect=true
```

--------------------------------

### Execute shell and file operations with TypeScript SDK

Source: https://sandbox.agent-infra.com/guide/start/agent-sandbox

Initializes the sandbox client, executes a shell command with error handling, writes a file, and retrieves the sandbox context.

```typescript
import { SandboxClient } from "@agent-infra/sandbox";

const sandbox = new SandboxClient({
  baseUrl: "http://localhost:8080",
});

const shell = await sandbox.shell.execCommand({
  command: "pwd && ls -la",
});

if (!shell.ok) {
  throw new Error("Shell command failed");
}

await sandbox.file.writeFile({
  file: "/home/gem/workspace/task.txt",
  content: "Build a small demo app",
});

const context = await sandbox.sandbox.getContext();
console.log(context.body);
```

--------------------------------

### Run OpenCode with OpenAI-compatible Endpoint

Source: https://sandbox.agent-infra.com/guide/advanced/opencode

Configures the container to use the standard OpenAI API endpoint.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e OPENCODE_PROVIDER="openai" \
  -e OPENCODE_BASE_URL="https://api.openai.com/v1" \
  -e OPENCODE_API_KEY="your-api-key" \
  -e OPENCODE_MODEL="your-model-id" \
  ghcr.io/agent-infra/sandbox:latest
```

--------------------------------

### Configure Execution Parameters

Source: https://sandbox.agent-infra.com/guide/basic/code-execution

Sets execution timeouts and retrieves environment information.

```python
# Use specific kernel with timeout
result = client.jupyter.execute_code(
    code="""
import time
import sys

print(f"Python version: {sys.version}")
time.sleep(2)
print("Processing complete")
""",
    kernel_name="python3.11",  # Specific kernel version
    timeout=30,  # 30 second timeout
)

# Get Jupyter environment info
info = client.jupyter.info()
print(f"Available kernels: {info.available_kernels}")
print(f"Default kernel: {info.default_kernel}")
print(f"Session timeout: {info.session_timeout_seconds}s")
print(f"Max sessions: {info.max_sessions}")
```

--------------------------------

### POST /v1/browser/actions

Source: https://sandbox.agent-infra.com/guide/basic/browser

Executes a specific GUI action such as mouse movement, clicking, typing, or keyboard shortcuts.

```APIDOC
## POST /v1/browser/actions

### Description
Executes a GUI action based on the provided action type and parameters.

### Method
POST

### Endpoint
/v1/browser/actions

### Request Body
- **action_type** (string) - Required - The type of action to perform (e.g., MOVE_TO, CLICK, TYPING, SCROLL, HOTKEY).
- **x** (integer) - Optional - X coordinate for mouse actions.
- **y** (integer) - Optional - Y coordinate for mouse actions.
- **text** (string) - Optional - Text input for TYPING action.
- **dx** (integer) - Optional - Horizontal scroll amount.
- **dy** (integer) - Optional - Vertical scroll amount.
- **keys** (array) - Optional - Array of keys for HOTKEY action.

### Request Example
{
  "action_type": "MOVE_TO",
  "x": 100,
  "y": 100
}
```

--------------------------------

### List Registered Skills

Source: https://sandbox.agent-infra.com/guide/basic/skills

Retrieve metadata for all currently registered skills.

```bash
curl "http://localhost:8080/v1/skills/metadatas"
```

--------------------------------

### Implement a basic MCP agent in Python

Source: https://sandbox.agent-infra.com/guide/basic/mcp

Defines an MCPAgent class to interface with the sandbox via HTTP requests and demonstrates a workflow for browsing and saving page content.

```python
import asyncio
from openai import AsyncOpenAI

class MCPAgent:
    def __init__(self, sandbox_url="http://localhost:8080"):
        self.sandbox_url = sandbox_url
        self.client = AsyncOpenAI()

    async def call_tool(self, tool_name, **kwargs):
        """Call an MCP tool through the sandbox"""
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.sandbox_url}/mcp",
                json={
                    "method": "tools/call",
                    "params": {
                        "name": tool_name,
                        "arguments": kwargs
                    }
                }
            )
            return response.json()

    async def browse_and_analyze(self, url):
        """Example: Browse a page and analyze content"""
        # Navigate to page
        await self.call_tool("browser_navigate", url=url)

        # Take screenshot
        screenshot = await self.call_tool("browser_screenshot")

        # Extract content
        content = await self.call_tool("browser_extract")

        # Save content to file
        await self.call_tool("file_write",
                           path="/tmp/content.txt",
                           content=content["text"])

        return {
            "screenshot": screenshot,
            "content": content,
            "saved_to": "/tmp/content.txt"
        }
```

--------------------------------

### Run Specific AIO Sandbox Version

Source: https://sandbox.agent-infra.com/guide/start/quick-start

Commands to run a specific version of the sandbox, with options for standard or China mirror registries.

```bash
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:1.11.0

# or use the public China mirror
docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.11.0
```

--------------------------------

### Retrieve Runtime Information

Source: https://sandbox.agent-infra.com/guide/basic/code

Fetches metadata about the available runtimes from the info endpoint.

```bash
curl "http://localhost:8080/v1/code/info"
```

--------------------------------

### Retrieve Runtime Information

Source: https://sandbox.agent-infra.com/guide/basic/nodejs

Fetches metadata about the current Node.js runtime environment.

```bash
curl "http://localhost:8080/v1/nodejs/info"
```

--------------------------------

### POST /v1/bash/exec

Source: https://sandbox.agent-infra.com/guide/basic/bash

Executes a bash command in the sandbox environment.

```APIDOC
## POST /v1/bash/exec

### Description
Executes a specified bash command. The response indicates if the request was accepted, and the command status should be monitored via the returned data.

### Method
POST

### Endpoint
/v1/bash/exec

### Request Body
- **command** (string) - Required - The bash command to execute.
- **timeout** (integer) - Optional - Execution timeout in seconds.
```
Tokens:
Raw