# Virtual Machine Sandbox Environment

> Master Agent virtual machine execution environments, session directory isolation, persistent volume mounts, startup scripts, and troubleshooting.

Source: https://doc.fastgpt.io/guide/build/agentv2/vm
Last Updated: 2026-11-12

The Virtual Machine (VM) provides Chat Agent V2 with an isolated code execution sandbox, persistent file I/O, and runtime dependency management.

## What is a Virtual Machine

When analyzing complex spreadsheets, performing mathematical computations, rendering dynamic charts, or executing Skills, agents require a genuine operational runtime. The virtual machine provides an isolated containerized environment (specific Python, Node.js, and system package versions depend on the configured sandbox image), allowing agents to write and run scripts, handle errors, and generate downloadable file assets.

Virtual machine execution relies on backend sandbox services (such as OpenSandbox or Sealos Devbox). Self-hosted operators must configure sandboxes according to the [Deployment Guide](https://doc.fastgpt.io/self-host).

***

## Architecture and Directory Layout

The platform isolates virtual machine files by tenant, application, and session identifiers:

```
<workspaceRoot>/
  ├── sessions/
  │     └── <chatId>/             # Session-specific directory isolating uploaded and generated files
  └── projects/
        └── <versionId>/          # Shared directory mounting published Skill version bundles
```

* **Session-Level Isolation**: Each conversation uses a dedicated workspace path `sessions/<chatId>`, where user-uploaded files mount automatically.
* **Automatic Dialog File Injection**: Files uploaded in the chat input box are automatically synchronized into the session workspace's `user_files/` directory before execution begins, allowing the Agent to read and process them via local paths.
* **State Persistence and Reset**: The same `chatId` reuses its session directory. Sandbox instances are scoped by source, application, and user. Restarting a chat changes its context and directory; sandbox lifecycle policies govern instance recycling and volume retention.
* **Security Isolation and Command Encoding**: Containers enforce CPU, memory, disk I/O, and network boundaries, and all executed commands are Base64-encoded before decoding inside the container to prevent shell injection.

***

## Virtual Machine Lifecycle

During environment initialization and execution, the platform manages the sandbox through discrete phases:

![Agent sandbox initialization](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/diagrams/sandbox-initialization.en.light.svg)

### Startup Scripts and Dependency Management

The application "Startup Script" runs after runtime acquisition, the initialization lock, and configuration and file preparation. It can install Python packages (e.g., `pip install matplotlib pandas`) or system binaries:

* **Preparation Order and Atomic Deployment**: Preparation runs in this order: Skill package injection → file injection → application startup script → Skill entrypoint scripts.
  1. **Skill Package Injection**: When published Skills are attached, each Skill bundle extracts into a temporary staging directory (`.tmp-<versionId>-<random>`) and atomically swaps into `projects/<versionId>` upon completion.
  2. **File Injection**: Files uploaded in the current conversation are written into the virtual machine.
  3. **Application Startup Script**: Runs inside the virtual machine workspace directory (such as `/workspace`) using the shell commands configured in the application panel.
  4. **Skill Entrypoint Script**: Each Skill's initialization script (such as `entrypoint.sh`) executes inside that Skill's directory.
* **Dual-Key State Deduplication (`~/.fastgpt/runtime/state.json`)**:
  * **Application Startup Script (SHA-256 Hash Deduplication)**: The runtime computes the SHA-256 hash of the startup script text and compares it against `~/.fastgpt/runtime/state.json`. Subsequent warm turns skip execution when the hash matches, and re-run automatically when the script text changes or the sandbox is rebuilt.
  * **Skill Entrypoint Script (Version ID Deduplication)**: Skill entrypoints deduplicate by immutable **Skill Version ID**, ensuring each published Skill version initializes once per sandbox instance lifecycle.

### Execution Constraints and Fault Tolerance

* **Preparation Failures**: Runtime acquisition or initialization lock failures return an error for the current preparation. Skill editor debugging uses a separate preparation branch.
* **Startup Timeout Protection**: Script execution duration is bounded by the `AGENT_SANDBOX_ENTRYPOINT_TIMEOUT_SECONDS` environment variable (defaults to 30 seconds; configurable from 1 to 600 seconds).
* **Non-blocking Resilience**: Non-zero exit codes or timeouts during script execution log warnings without crashing the conversational flow, allowing builders to inspect missing dependencies in debug panels.
* **Buffer Output Limits**: Script output retains the last 8 KiB and background service logs retain up to 4,000 characters; write large results to files and inspect the generated artifacts.

***

## Sandbox Debugging and File Manager

1. **Real-Time Status Tracking**: In the preview drawer, the interface shows the virtual machine status: **Preparing virtual machine**, **Upgrading virtual machine**, or **Virtual machine ready**.
2. **Virtual Machine File Manager**: Click the **Virtual Machine** icon button in the upper-right corner of the debug drawer to open the sandbox file and terminal manager, browse files, preview images (such as `revenue.png`), or download generated tables (such as `channel_summary.csv`).
3. **Diagnostics**: When scripts fail with missing module errors, inspect the startup script logs and return codes to verify that dependencies installed successfully.

![Virtual machine file manager displaying generated CSV and chart files](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/vm-files.png.webp)

## Next Steps

* Real-world data analysis: Follow [Intelligent Data Analysis Agent Case](https://doc.fastgpt.io/guide/getting-started/examples/data-analysis).
* Custom skill packages: Learn [Skill Initialization and Development](https://doc.fastgpt.io/guide/build/skill/initialization).
* Trace decision paths: Follow [Agent Debugging and Trace Inspection](https://doc.fastgpt.io/guide/build/agentv2/debug).
