Code Execution Sandbox
Relevant source files
The following files were used as context for generating this wiki page:
The Code Execution Sandbox is a specialized, isolated environment within the Onyx project designed to execute AI-generated code, build web applications, and process data using internal knowledge. It primarily supports the Onyx Craft feature, which acts as an AI coding agent to create artifacts like Next.js applications, documents, and interactive dashboards based on indexed company data.
The system ensures that code generated by LLMs is executed safely, preventing direct access to the host system while providing the agent with necessary tools such as Python (with data science libraries) and Next.js for real-time previews. This environment is managed through a lifecycle that includes pre-provisioning, active execution, idle monitoring, and automatic cleanup or snapshotting.
Sources: web/src/app/craft/README.md:21-25, web/src/app/craft/README.md:104-106
Sandbox Architectures
The project supports two distinct backends for the sandbox environment, configurable via the SANDBOX_BACKEND environment variable.
Self-Hosted Backend
The self-hosted version is typically used for development or simpler deployments. It relies on the host's filesystem and process-level isolation rather than containerization.
- Pathing: Uses
SANDBOX_BASE_PATH(defaulting to/tmp/onyx-sandboxes). - Isolation: Process-level only; lacks container isolation.
- Persistence: No automatic cleanup or snapshots are provided in this mode.
- Data Access: Utilizes symlinks to provide the agent access to the user's knowledge files.
Cloud (Production) Backend
The cloud backend is designed for multi-tenant production environments, providing robust isolation and session persistence.
- Isolation: Uses Pod-based isolation within a Kubernetes cluster with ClusterIP services.
- Persistence: Implements S3-based snapshots for session persistence, allowing users to restore sessions later.
- Lifecycle: Features automatic cleanup of idle sandboxes (defaulting to a 1-hour timeout).
- Container Structure: Each pod contains two containers:
sandbox: Runs the OpenCode agent and the Next.js preview server.file-sync: A sidecar container responsible for S3 file synchronization.
Sources: web/src/app/craft/README.md:52-70
Session Lifecycle and States
Sandboxes transition through several states to manage resources effectively, especially in cloud environments where a Celery background task monitors activity.
| State | Description |
|---|---|
| Provisioning | Sandbox is being created (triggered when user visits /craft). |
| Ready | Sandbox is active and waiting for the first user message. |
| Running | The OpenCode agent is currently processing a request. |
| Idle | No recent activity detected in the session. |
| Sleeping | Idle timeout reached; pod is terminated (K8s) and a snapshot is saved to S3. |
| Restored | User returns to a sleeping session; the snapshot is loaded into a new pod. |
Sources: web/src/app/craft/README.md:72-81
Lifecycle Flow Diagram
The following diagram illustrates how a sandbox session moves from provisioning to idle cleanup.
The diagram shows the transition between active execution and the "Sleeping" state handled by the Celery background worker.
Sources: web/src/app/craft/README.md:72-81, web/src/app/craft/README.md:100-106
Sandbox Workspace Structure
Every sandbox session is allocated an isolated directory structure to store code, outputs, and agent-specific configurations.
$SANDBOX_ROOT/
├── files/ # Symlinks to user's knowledge files
└── sessions/
└── {session_id}/
├── outputs/web/ # Next.js application code and build
├── .venv/ # Isolated Python virtual environment
├── .opencode/skills/ # Agent-specific skills/tools
├── attachments/ # Files uploaded by the user
├── AGENTS.md # Instructions provided to the agent
└── opencode.json # LLM and agent configuration
Sources: web/src/app/craft/README.md:83-93
Technical Stack and Components
The sandbox integrates multiple backend and frontend technologies to facilitate real-time code building and previewing.
Backend Infrastructure
- Agent: Uses the OpenCode CLI with ACP (Agent Communication Protocol), communicating via JSON-RPC 2.0 over stdin/stdout.
- Orchestration: FastAPI and SQLAlchemy manage session metadata, while Celery handles background tasks like sandbox cleanup.
- Storage: PostgreSQL stores session metadata, while S3-compatible storage is used for K8s snapshots.
Execution Environment
- Web Development: Pre-provisioned with Next.js 16, React 19, Tailwind CSS, shadcn/ui, and Recharts for building interactive dashboards.
- Python Data Science: Includes Python 3.11 equipped with
numpy,pandas, andmatplotlib.
Frontend Integration
- Real-time Preview: The web interface supports live output streaming and visibility into tool calls as the agent builds the application.
- State Management: Uses Zustand for managing the state of the sandbox preview and session.
Sources: web/src/app/craft/README.md:118-140, CONTRIBUTING.md:120-130
Configuration and Limits
The behavior of the sandbox is controlled through several environment variables and system limits.
| Category | Key Variables / Limits |
|---|---|
| Core | ENABLE_CRAFT, SANDBOX_BACKEND (local vs kubernetes) |
| Lifecycle | SANDBOX_IDLE_TIMEOUT_SECONDS (Default: 3600s) |
| Concurrency | Max concurrent sandboxes per organization (Default: 10) |
| File Uploads | 50MB per file; 20 files per session; 200MB total limit |
| Rate Limits | Free users: 5 messages total; Paid users: 25 messages/week |
Sources: web/src/app/craft/README.md:108-116
Background Task Coordination
The sandbox system relies on the Celery Primary Worker and User File Processing Worker to maintain synchronization between the user's indexed knowledge and the isolated environment.
The sequence shows the coordination between the web frontend, API, and the background workers responsible for lifecycle management.
Sources: AGENTS.md:30-40, web/src/app/craft/README.md:72-81
Conclusion
The Code Execution Sandbox provides a secure and scalable infrastructure for AI agents to operate as developers within the Onyx ecosystem. By separating execution into isolated pods or directories and implementing a robust snapshotting system, it allows for sophisticated "Crafting" of web applications and data reports while maintaining system security and resource efficiency.