Vercel Sandbox Management
Relevant source files
The following files were used as context for generating this wiki page:
Vercel Sandbox Management is a core system within the Recoup project designed to manage ephemeral, isolated Linux microVM environments. These sandboxes are used to safely execute code, run AI agent tasks, and evaluate generated outputs in a secure, reproducible manner.
The system handles the full lifecycle of a sandbox, including creation (or retrieval of existing ones), provisioning with necessary tools like OpenClaw and Claude Code, integration with GitHub repositories for persistence, and state management via snapshots.
Sources: src/sandboxes/writeReadme.ts:31-35, src/tasks/setupSandboxTask.ts:13-17
Sandbox Lifecycle and Provisioning
The sandbox management logic follows a structured workflow to ensure that every environment is consistent and ready for task execution. This is primarily orchestrated through the provisionSandbox function and background tasks.
Provisioning Workflow
When a sandbox is provisioned, the following sequence occurs:
- Tooling Installation: OpenClaw CLI and gateways are installed and configured.
- Repository Setup: The system ensures a dedicated GitHub repository exists for the account and clones it into the sandbox root.
- Documentation: A standard
README.mdis written to the sandbox root containing metadata like Sandbox ID and Account ID. - Organization Sync: Relevant organization repositories are cloned and synced to their latest remote states to prevent stale commits.
- Environment Setup: Specific folder structures for orgs and artists are created using internal "skills".
Sources: src/sandboxes/provisionSandbox.ts:25-50, src/sandboxes/ensureGithubRepo.ts:25-45, src/tasks/runSandboxCommandTask.ts:47-75
The diagram above illustrates the sequential steps taken to prepare a Vercel Sandbox for operation.
Sources: src/sandboxes/provisionSandbox.ts:25-48
Core Components and Functions
The management system relies on several key functions to handle different aspects of the sandbox environment.
Primary Functions
| Function | File | Description |
|---|---|---|
getOrCreateSandbox | getOrCreateSandbox.ts | Retrieves an existing sandbox or triggers creation via the Recoup API. |
provisionSandbox | provisionSandbox.ts | Orchestrates the installation of tools, git setup, and initial file writes. |
ensureGithubRepo | ensureGithubRepo.ts | Idempotently ensures a GitHub repo exists and is initialized in the sandbox. |
writeReadme | writeReadme.ts | Writes environment details to README.md unless already present. |
runClaudeCodeAgent | runClaudeCodeAgent.ts | Executes the Claude Code agent within the sandbox in detached mode. |
Sources: src/sandboxes/getOrCreateSandbox.ts:20-40, src/sandboxes/provisionSandbox.ts:25-30, src/sandboxes/ensureGithubRepo.ts:25-30, src/sandboxes/runClaudeCodeAgent.ts:20-30
Sandbox Execution Tasks
The project uses trigger.dev to manage background tasks that interact with sandboxes.
- setup-sandbox: Creates a personal sandbox, provisions it, takes a final snapshot, and shuts it down. Sources: src/tasks/setupSandboxTask.ts:13-25
- run-sandbox-command: Connects to an existing sandbox to run a specific shell command, then persists changes. Sources: src/tasks/runSandboxCommandTask.ts:22-35
- coding-agent: A specialized task that clones a monorepo, runs a Claude Code AI agent to perform work, and creates PRs. Sources: src/tasks/codingAgentTask.ts:20-35
Git and Persistence Strategy
Persistence is achieved through two mechanisms: GitHub synchronization and Vercel Sandbox snapshots.
GitHub Integration
The ensureGithubRepo function checks if an account has a dedicated repository. If not, it creates one and updates the account's metadata. The sandbox root is then initialized with this repo. To prevent conflicts, syncOrgRepos and syncMonorepoSubmodules are used to perform hard resets to the latest remote main or base branches before any automated changes are made.
Sources: src/sandboxes/ensureGithubRepo.ts:47-70, src/sandboxes/git/syncOrgRepos.ts:23-40, src/sandboxes/git/syncMonorepoSubmodules.ts:20-35
Snapshot Management
After task completion, the system typically takes a snapshot via sandbox.snapshot(). This captures the entire file system state of the microVM. The snapshot ID is then persisted to the Recoup API for the specific account, allowing subsequent tasks to resume from the exact same state.
Sources: src/tasks/runSandboxCommandTask.ts:101-105, src/tasks/setupSandboxTask.ts:38-42
The sequence diagram shows how data flows between the task runner, the sandbox environment, and external persistence layers.
Sources: src/tasks/runSandboxCommandTask.ts:47-115, src/tasks/setupSandboxTask.ts:25-55
Environment Configuration
Sandboxes are configured with specific environment variables to allow tools like OpenClaw and Claude Code to authenticate with external services.
| Variable | Description | Source |
|---|---|---|
RECOUP_API_KEY | Required for internal Recoup API interactions. | getSandboxEnv.ts |
RECOUP_ACCOUNT_ID | Identifies the owner of the sandbox session. | getSandboxEnv.ts |
GITHUB_TOKEN | Used for git operations and repository management. | getSandboxEnv.ts |
CLAUDE_CODE_OAUTH_TOKEN | Required for running the claude CLI agent. | runClaudeCodeAgent.ts |
Sources: src/sandboxes/getSandboxEnv.ts:10-25, src/sandboxes/runClaudeCodeAgent.ts:40-45
Summary
Vercel Sandbox Management provides a robust, ephemeral infrastructure for code execution. By automating the provisioning of Linux microVMs and integrating them with GitHub and AI agents (Claude Code), the system ensures that every task runs in a clean, documented, and reproducible environment. Persistence is carefully handled through a combination of git synchronization and microVM snapshots to maintain state across different background task executions.