> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Sandbox

> Declarative sandbox architecture — every conversation gets its own isolated development environment

When an Expert needs to "get things done" — write code, run programs, operate on files — it doesn't execute on some shared server. Instead, it operates within a dedicated, isolated cloud container. This is Profy's declarative sandbox architecture: every conversation has its own complete development environment, fully isolated from others, disposable after use.

## Why a Sandbox?

<CardGroup cols={2}>
  <Card title="Security Isolation" icon="shield">
    Code executed by AI may contain errors or even risks. The sandbox ensures all operations are confined within the container, unable to affect the host system or other users.
  </Card>

  <Card title="Consistent Environment" icon="check">
    Pre-installed with a complete development toolchain (Node.js, Python, system tools), so the Expert doesn't spend time setting up — it can start working immediately.
  </Card>

  <Card title="Persistent State" icon="database">
    The file system persists throughout the conversation. Code written, dependencies installed, and files generated by the Expert are still there when the next message arrives.
  </Card>

  <Card title="On-Demand Start" icon="bolt">
    Sandboxes are only created when the Expert actually needs to execute tools — pure conversations incur zero resource cost.
  </Card>
</CardGroup>

## Sandbox Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Waiting: Conversation starts (no sandbox)
    Waiting --> Creating: Expert's first tool call
    Creating --> Running: Container ready (sub-second)
    Running --> Running: Execute tool operations
    Running --> Sleeping: Conversation idle timeout
    Sleeping --> Running: User sends new message
    Running --> Terminated: Session ends / manually closed
    Sleeping --> Terminated: Retention period exceeded
    Terminated --> [*]
```

<Steps>
  <Step title="Lazy Provision">
    Sandboxes are not created when the conversation starts, but only when the Expert first needs to execute a tool operation. Pure text conversations consume zero resources.
  </Step>

  <Step title="Sub-Second Warm Start">
    Based on pre-warmed container images, sandboxes typically go from creation to ready in under 1 second. Users barely notice any wait.
  </Step>

  <Step title="Cross-Message Persistence">
    Multiple messages within the same session share a single sandbox instance. Dependencies installed in the first message are still available in the fifth.
  </Step>

  <Step title="Idle Hibernation">
    When the conversation pauses, the sandbox automatically hibernates, releasing compute resources. The file system persists through cloud file storage (CFS), nothing is lost.
  </Step>

  <Step title="Seamless Resume">
    When the user sends another message, the sandbox is woken up to its previous file system state. The Expert can seamlessly continue its previous work.
  </Step>
</Steps>

## Image Pre-Baking

The sandbox is not an empty container — it comes pre-installed with a rich development toolchain, ready for the Expert to use out of the box:

<Accordion title="Programming languages and package managers">
  * **Node.js** + bun (JavaScript/TypeScript full-stack)
  * **Python 3** + uv package manager (data science + AI development)
  * **TypeScript** compiler + language server
  * **Biome** code formatting and static analysis
</Accordion>

<Accordion title="Data science stack">
  * pandas, numpy, matplotlib, seaborn
  * scipy, scikit-learn
  * Pillow image processing
  * openpyxl Excel handling
</Accordion>

<Accordion title="Document processing capabilities">
  * Pandoc document format conversion
  * WeasyPrint PDF rendering
  * Tesseract OCR text recognition
  * ImageMagick image processing
  * Poppler PDF tools
</Accordion>

<Accordion title="Web development frameworks">
  * TanStack Start (pre-baked + node\_modules)
  * FastAPI / Flask (Python Web)
  * Complete HTTP client toolchain
</Accordion>

<Tip>
  The core idea behind pre-baking is "shifting wait time from runtime to build time." Users don't need to wait for `npm install` or `pip install` — hundreds of megabytes of dependencies are already installed during image build.
</Tip>

## Working Directory Architecture

```mermaid theme={null}
graph TD
    subgraph Sandbox File System
        Root[/home/user/]
        Root --> Project[project/<br/>Read-only seed template]
        Root --> Workspace[workspace/<br/>Writable working area]
        Project --> Web[web/<br/>Pre-baked web project]
        Workspace --> UserWeb[web/<br/>User's web project]
        Workspace --> Scripts[scripts/<br/>Script files]
        Workspace --> Data[data/<br/>Data files]
    end
```

| Path                    | Permissions | Purpose                                                         |
| ----------------------- | ----------- | --------------------------------------------------------------- |
| `/home/user/project/`   | Read-only   | Pre-baked template files in the image (including node\_modules) |
| `/home/user/workspace/` | Read-write  | Expert's actual working directory, all creation happens here    |

This design lets the Expert quickly start from a template (zero installation delay) while ensuring the user's actual work is not affected by subsequent image updates.

## Dev Server Lazy Start

Web preview is a commonly used Expert capability — letting users see the visual effects of code in real time. But a Dev Server is a resource-intensive process:

```mermaid theme={null}
sequenceDiagram
    participant Expert as Expert
    participant RT as Runtime
    participant SB as Sandbox

    Note over Expert,SB: Regular conversation (no web preview needed)
    Expert->>RT: Write Python script
    RT->>SB: write + bash execute
    Note over SB: No Dev Server started, resources saved

    Note over Expert,SB: Web preview needed
    Expert->>RT: Call website_init tool
    RT->>SB: Start Dev Server
    SB-->>RT: Preview URL ready
    RT-->>Expert: Website preview panel opens
```

**Invariant**: The only entry point for starting a Dev Server is the Expert proactively calling the initialization tool. Conversations that don't need preview (data analysis, script execution, document processing) never pay the memory and CPU cost of a Dev Server.

## Network and Security Policies

Sandboxes have controlled network access capabilities:

<CardGroup cols={2}>
  <Card title="Outbound Access" icon="arrow-up-right">
    Experts can access external APIs, download resources, and make network requests. This is essential for web development and data collection.
  </Card>

  <Card title="Process Isolation" icon="lock">
    Each sandbox is an independent Linux container with complete process namespace isolation. One user's operations can never affect another user.
  </Card>

  <Card title="Resource Limits" icon="gauge">
    CPU, memory, and disk usage all have container-level hard limits, preventing malicious or runaway programs from exhausting shared infrastructure.
  </Card>

  <Card title="File System Isolation" icon="folder-tree">
    Cloud file storage is mounted with per-session isolation, inaccessible across sessions. Even different sessions from the same user cannot see each other's files.
  </Card>
</CardGroup>

## Provider Abstraction

The sandbox system uses a Provider abstraction design, allowing the underlying implementation to be transparently swapped:

```mermaid theme={null}
graph TD
    RT[Agent Runtime] --> |Unified SDK Interface| Provider[Provider Abstraction Layer]
    Provider --> E2B[E2B Provider<br/>Cloud Containers]
    Provider --> Future[Future Providers<br/>Extensible]

    E2B --> |provision| Create[Create Container]
    E2B --> |resume| Wake[Wake Container]
    E2B --> |pause| Sleep[Hibernate Container]
    E2B --> |terminate| Destroy[Destroy Container]
```

The Runtime doesn't care about the specific container implementation details — it interacts with sandboxes through a unified Provider interface. This means new container providers can be seamlessly integrated in the future without any changes to the upper-layer Agent logic.

## File Sync and Preview

Files created by the Expert in the sandbox can be previewed and downloaded by users in real time:

* **Code files**: Displayed with syntax highlighting, supporting diff comparison
* **Web projects**: Real-time preview via Dev Server, supporting HMR hot reload
* **Data files**: Tables and charts rendered inline
* **Documents**: PDF and Markdown instant preview

Users can also sync files from the sandbox to cloud storage for access after the conversation ends.

<Note>
  The sandbox is the technical foundation of Profy's "AI doesn't just talk, it does" philosophy. Without it, Experts can only generate text; with it, Experts can write code, run programs, create projects, generate documents — working like a true digital colleague.
</Note>

## Design Trade-offs

| Decision          | Choice                                | Rationale                                                    |
| ----------------- | ------------------------------------- | ------------------------------------------------------------ |
| Start timing      | Lazy loading (on first tool call)     | Pure conversations pay zero resource cost                    |
| Persistence layer | Cloud File Storage (CFS)              | Cross-container state retention, no file loss on hibernation |
| Template strategy | Pre-baked node\_modules               | Zero wait for users, trading space for time                  |
| Dev Server        | On-demand start only                  | Zero overhead for non-web scenarios                          |
| Image updates     | Working directory separated from seed | Upgrading images doesn't break user projects                 |