Sandbox Command Tasks
Relevant source files
The following files were used as context for generating this wiki page:
Sandbox Command Tasks are a core set of background operations in the Recoup project designed to manage isolated Linux microVM environments. These tasks leverage Vercel Sandboxes to execute commands, run AI-driven coding agents, and manage persistent state via GitHub integrations and snapshots.
The system supports a variety of workflows, including initial environment provisioning, direct command execution, and complex multi-step coding agent tasks that can create or update Pull Requests across various submodules. Sources: src/tasks/runSandboxCommandTask.ts:16-20, src/tasks/setupSandboxTask.ts:9-13, src/sandboxes/writeReadme.ts:54-59
Core Task Types
The project defines several specialized Trigger.dev tasks to handle different sandbox lifecycles and operational requirements.
Setup and Command Execution
- Setup Sandbox Task (
setup-sandbox): Handles the creation and full provisioning of a personal sandbox. It installs necessary tools (OpenClaw), configures GitHub repositories, establishes folder structures, and persists the state in a snapshot before shutting down. Sources: src/tasks/setupSandboxTask.ts:14-25 - Run Sandbox Command Task (
run-sandbox-command): Connects to an existing sandbox to run arbitrary commands with arguments. It ensures the environment is synchronized with remote repositories and takes a new snapshot after execution. Sources: src/tasks/runSandboxCommandTask.ts:21-27
AI Coding Agents
- Coding Agent Task (
coding-agent): A complex workflow that clones a monorepo, syncs submodules, and runs the Claude Code agent to perform development work based on a user prompt. Sources: src/tasks/codingAgentTask.ts:16-22 - Update PR Task (
update-pr): Resumes a sandbox from a specific snapshot to apply feedback to an existing branch and push updates to a Pull Request. Sources: src/tasks/updatePRTask.ts:14-18
Sandbox Lifecycle and Provisioning
The provisioning process ensures that every sandbox is a "social-ready" development environment. This includes installing the OpenClaw toolset, configuring AI Gateway access, and setting up a README.md that describes the isolated microVM. Sources: src/tasks/runSandboxCommandTask.ts:52-65, src/sandboxes/writeReadme.ts:38-50
The diagram above illustrates the standard sequence for preparing a sandbox for execution. Sources: src/tasks/runSandboxCommandTask.ts:45-100, src/tasks/setupSandboxTask.ts:25-55
AI Agent Integration
The system utilizes Claude Code as a primary agent for performing changes within the sandbox. The coding-agent task delegates significant Git operations to the agent, including branching, committing, and opening Pull Requests using the GitHub CLI (gh).
PR Creation Logic
When the agent completes a task, it follows a two-step process:
- Mono Repo Root Changes: Any changes to the root (like progress files) are committed and pushed directly to the
mainbranch. - Submodule Changes: For each changed submodule, the agent creates a unique branch (e.g.,
agent/slug-timestamp), commits changes, and creates a PR. Sources: src/sandboxes/pushAndCreatePRsViaAgent.ts:52-85
| Feature | Description |
|---|---|
| Branch Naming | Uses a slugified version of the prompt + timestamp (agent/slug-12345). |
| Sentinel Lines | The agent outputs PR_CREATED: <URL> which is parsed to notify the system of success. |
| Context Injection | Previous stdout is injected into subsequent agent calls to maintain state. |
Sources: src/tasks/codingAgentTask.ts:60-65, src/sandboxes/pushAndCreatePRsViaAgent.ts:40-50
Data Models and Schemas
Task interactions are strictly validated using Zod schemas to ensure payload integrity.
Sandbox Result Schema
The output of a sandbox command includes the process results and snapshot metadata.
export const sandboxResultSchema = z.object({
stdout: z.string(),
stderr: z.string(),
exitCode: z.number(),
snapshot: z.object({
id: z.string(),
expiresAt: z.string(),
}),
});
Sources: src/schemas/sandboxSchema.ts:22-30
Execution Configuration
Tasks are configured with specific timeouts and retry logic to handle the long-running nature of sandbox operations.
| Task ID | Max Duration | Retry Policy |
|---|---|---|
run-sandbox-command | 15 Minutes | 1 Attempt (Non-idempotent) |
setup-sandbox | 15 Minutes | 0 Attempts |
coding-agent | 30 Minutes | 0 Attempts |
update-pr | 15 Minutes | 0 Attempts |
Sources: src/tasks/runSandboxCommandTask.ts:23-28, src/tasks/setupSandboxTask.ts:18-21, src/tasks/codingAgentTask.ts:20-23, src/tasks/updatePRTask.ts:16-19
Git and Repository Synchronization
Before executing commands, the sandbox environment is synchronized to prevent "stale" snapshots from causing force-push issues. This involves running git fetch origin main and git reset --hard origin/main across all organizational repositories. This ensures the sandbox state matches the latest remote commits before the agent begins its work. Sources: src/tasks/runSandboxCommandTask.ts:74-77, src/sandboxes/tests/syncOrgRepos.test.ts:45-55
Conclusion
Sandbox Command Tasks provide a robust, automated infrastructure for executing code and AI agent activities in isolation. By combining ephemeral microVMs with persistent snapshots and GitHub integration, the system enables complex developer workflows (like PR feedback loops) to be handled entirely by background tasks and AI agents.