Code Execution Sandboxes
Relevant source files
The following files were used as context for generating this wiki page:
Code Execution Sandboxes provide isolated Linux microVM environments designed to evaluate account-generated code, execute AI agent outputs safely, and perform reproducible data analysis tasks. These environments are ephemeral, automatically stopping after a predefined timeout period, and are integrated with GitHub repositories to maintain persistent file state through snapshots.
In the Recoup ecosystem, sandboxes are the primary tool for the AI assistant ("Recoup"). The assistant uses the prompt_sandbox tool to create and edit documents, generate marketing materials, build release plans, and perform complex multi-step data analysis.
Sources: app/api/sandboxes/route.ts:25-30, lib/chat/const.ts:11-18
Sandbox Lifecycle and Management
The system manages sandboxes through a set of RESTful API endpoints that handle creation, status retrieval, snapshot updates, and environment cleanup.
Sandbox Creation and Execution
Sandboxes are created as isolated microVMs. During creation, an optional command can be provided for immediate execution within the environment. If a command is executed, the response includes a runId to track the specific execution.
The diagram shows the branching logic for sandbox management via the API.
Sources: app/api/sandboxes/route.ts:25-50
Retrieval and Status
Users can list all sandboxes associated with an account. The system returns the lifecycle state, remaining timeout, and creation timestamp for each active environment. This process involves parallel fetching of sandbox statuses and repository file trees to optimize performance.
Sources: app/api/sandboxes/route.ts:63-75, lib/sandbox/tests/getSandboxesHandler.test.ts:220-245
AI Integration: Claude Code Execution
A specialized integration exists for running Claude-generated code within the sandbox. This is facilitated by a script that executes the claude command-line tool with specific permissions.
Execution Logic
The system writes a shell script (ralph-once.sh) to the sandbox filesystem. This script executes Claude using the opus model with the --permission-mode acceptEdits flag. The environment is provisioned with the ANTHROPIC_API_KEY to allow the AI to perform its tasks.
This sequence diagram illustrates how the API server orchestrates Claude code execution inside the isolated environment.
Sources: lib/sandbox/runClaudeCode.ts:1-25, lib/sandbox/tests/runClaudeCode.test.ts:20-40
File System and Repository Integration
Sandboxes are deeply integrated with GitHub to provide a persistent context for ephemeral environments. Each account is associated with a snapshot that links to a GitHub repository.
File Retrieval
The getSandboxesFileHandler retrieves file contents directly from the GitHub repository associated with the account's snapshot. It supports:
- Submodule Resolution: Automatically resolves paths that reside within Git submodules.
- Binary Detection: Detects binary files (images, PDFs, fonts) and returns them as base64-encoded strings.
- Text Encoding: Plain text files (markdown, CSV, etc.) are returned as standard strings.
File Uploads
Files can be uploaded to the sandbox via a POST request that accepts a list of URLs. The system downloads these files (often from temporary storage like Vercel Blob) and commits them to the associated GitHub repository.
Sources: lib/sandbox/getSandboxesFileHandler.ts:20-50, lib/sandbox/validatePostSandboxesFilesRequest.ts:10-25, lib/sandbox/tests/getSandboxesFileHandler.test.ts:160-185
API Reference
Sandbox Endpoints
| Endpoint | Method | Description | Key Parameters |
|---|---|---|---|
/api/sandboxes | POST | Creates a new microVM | command, args, cwd |
/api/sandboxes | GET | Lists active sandboxes | sandbox_id (optional filter) |
/api/sandboxes | PATCH | Updates base snapshot ID | snapshotId (required) |
/api/sandboxes | DELETE | Removes repo and snapshot | account_id (org keys only) |
/api/sandboxes/files | POST | Uploads files to the environment | files (URL/name array), path |
Sources: app/api/sandboxes/route.ts:10-120, lib/sandbox/validatePostSandboxesFilesRequest.ts:10-20
Data Structures
Sandbox Status Object:
sandboxId: String (Unique identifier)sandboxStatus: String (e.g., "running")timeout: Number (Milliseconds until auto-stop)createdAt: ISO Date StringrunId: String (Optional, for command tracking)
Sources: app/api/sandboxes/route.ts:47-52, lib/sandbox/tests/getSandboxesHandler.test.ts:80-95
Security and Authentication
Sandbox operations require strict authentication using either an x-api-key header or an Authorization: Bearer token. The validateAuthContext utility ensures that:
- Individual accounts can only access their own sandboxes.
- Organization keys can access or modify sandboxes for any account within their organization via the
account_idoverride. - Command execution is isolated within the microVM to prevent host system interference.
Sources: app/api/sandboxes/route.ts:108-115, lib/sandbox/validatePostSandboxesFilesRequest.ts:38-45
Summary
Code Execution Sandboxes serve as the operational backbone for AI-driven tasks in the project. By combining ephemeral microVMs with GitHub-backed snapshots, the system provides a secure, reproducible, and persistent environment for complex operations like release management and automated code generation. Management is unified through a standard API that handles the lifecycle from provisioning to snapshot cleanup.