Skip to main content
This document introduces the XpertAI Sandbox Plugin from architectural and capability perspectives, emphasizing extensibility, reliability, and security. This document does not contain interface or code details and is suitable for product, architecture, and integration audiences.

​
1. Feature Overview

Sandbox Plugin provides agents with an isolated execution and file operation environment for:
  • Executing code and tool calls, supporting multiple languages and toolchains.
  • Isolating working directories for users and projects, enabling multi-tenant and multi-scenario execution.
  • Automating sandbox instance management, monitoring, and lifecycle governance.

​
2. Architecture Overview

Sandbox Plugin consists of three coordinated layers:
  • Orchestration Layer: Handles request routing, permission validation, task scheduling, and lifecycle management.
  • Execution Layer: Provided by Sandbox Provider with runtime environments, with built-in Docker sandbox by default.
  • Tool Layer: Tool sets access the sandbox through a unified protocol, supporting file, terminal, browser, and project capabilities.
The overall workflow follows a “request → select Provider → create or reuse sandbox → execute task → monitor and recycle” pattern, ensuring consistent observability and maintainability.

​
3. Extensibility: Custom Sandbox Providers

One of the core capabilities of Sandbox Plugin is the Provider plugin mechanism. Through custom Providers, different runtime infrastructures can be integrated, such as:
  • Docker/Podman container systems
  • Runloop, Modal, Daytona
  • Remote virtual machines or secure sandbox services
Custom Providers must implement the unified sandbox protocol and register as optional strategies. The system selects matching Providers at runtime. This allows extending new execution backends without modifying core orchestration logic.

​
4. Built-in Docker Sandbox Capabilities and Monitoring

The built-in Docker sandbox provides comprehensive runtime support:
  • Auto-creation and reuse: Reuse existing containers by user, project, or environment dimensions to improve performance and resource utilization.
  • Runtime configuration and resource governance: Supports network, port, CPU, memory, and shared memory configuration for different workload demands.
  • Lifecycle governance: Ensures containers are recyclable, states are recoverable, and exceptions are addressable through delayed cleanup and periodic reconciliation.
  • Observability: Unified labeling identifies tenant, purpose, and environment ownership for easier monitoring, tracing, and operations.

​
5. Security Design

Sandbox Plugin follows the principle of least privilege and isolation, prioritizing:
  • Multi-tenant isolation: File and execution spaces of different tenants are isolated through volumes and contexts.
  • Access control: Sensitive operations and management interfaces are protected by permissions.
  • Resource limits: Configurable CPU, memory, and runtime limits prevent resource abuse.
  • Read-only and restricted execution: Support read-only access scenarios to reduce data plane risks.

​
6. Maintainability and Reliability

Sandbox Plugin design emphasizes long-term maintainability:
  • Modular orchestration: Separate orchestration, execution, and tool layers for easier extension and evolution.
  • Task traceability: Unified scheduling and reconciliation mechanisms reduce state drift.
  • Auto-recovery: Exceptional or disconnected containers can be identified and repaired.
  • Ops-friendly: Provides clear lifecycle boundaries and monitoring entry points.

​
7. Tool Ecosystem and Use Cases

The Sandbox tool set provides standardized capability interfaces for agents, including:
  • File system and code execution
  • Terminal commands and project management
  • Browser automation and content generation
The unified protocol of the tool layer makes adding new tools or extending capabilities easier, forming a complete loop with Provider extension.