Sandbox Overview

Sandboxes are the execution backbone of CodeCourier. Every time an AI coding agent runs a task, writes code, or executes a command, it does so inside a sandbox -- an isolated, ephemeral cloud Linux virtual machine powered by E2B. This architecture ensures that agent activity is fully contained, reproducible, and secure, with no risk to your local machine or production infrastructure.

What is a Sandbox?

A sandbox in CodeCourier is a fully featured Linux environment running in the cloud. Each sandbox comes with a complete file system, network access, process execution capabilities, and pre-installed development tools. Under the hood, CodeCourier uses the E2B SDK to provision these environments on demand. When you launch a sandbox, E2B creates a lightweight virtual machine from a template, injects your configuration (API keys, system prompts, skills, learnings), and hands control to your chosen AI coding agent.

Sandboxes are not containers -- they are full micro-VMs with their own kernel, providing stronger isolation guarantees than Docker. This means an AI agent running inside a sandbox cannot affect other sandboxes, your host system, or any other user's environment.

Why Sandboxes Matter

Running AI coding agents on your local machine poses real risks. An agent with file system access can overwrite files, install malicious packages, or access secrets stored in your environment. By running every agent task inside a sandbox, CodeCourier eliminates these risks entirely.

• Security -- Each sandbox is an isolated micro-VM. Agents cannot escape to the host, access other sandboxes, or read files outside their environment.
• Reproducibility -- Sandboxes start from a known template state. Every run begins with the same base environment, making results deterministic and debuggable.
• Resource control -- You configure the CPU, memory, and timeout for each sandbox. If an agent runs for too long or consumes too much memory, the sandbox is killed automatically.
• Parallel execution -- Multiple sandboxes can run simultaneously, each working on a different task. Workflow steps, issue sessions, and standalone sandboxes all operate independently.

Architecture

The sandbox architecture in CodeCourier involves three layers:

E2B Infrastructure

E2B provides the virtual machine infrastructure. When CodeCourier requests a sandbox, E2B provisions a micro-VM from a template (e.g., the claude template for Claude Code sandboxes or theopencode template for OpenCode). The provisioned VM includes a base Linux environment with Node.js, Python, Git, and common development tools pre-installed.

Trigger.dev Orchestration

Long-running sandbox operations are managed by Trigger.dev background tasks. When a workflow run starts, Trigger.dev creates the E2B sandbox, runs setup scripts (Git clone, dependency installation, configuration injection), executes the AI agent command, streams output back to the database, and handles cleanup on completion or failure.

Convex Database

Every sandbox has a corresponding record in the Convex database that tracks its state. The database stores the sandbox's status (creating, running, paused,killed, or error), its configuration (template, timeout, CPU, memory), its relationships to runs and workflows, and metadata like PR URLs, branch names, and learning extraction status. Because Convex is reactive, the dashboard UI updates in real time as sandbox state changes.

Types of Sandboxes

Sandboxes in CodeCourier are created in different contexts, each with slightly different lifecycle characteristics:

Standalone Sandboxes

Created directly from the Sandboxes page. These are interactive environments where you can send messages to the AI agent, view streaming terminal output, and manually manage the sandbox lifecycle. Standalone sandboxes are ideal for ad-hoc tasks, debugging, and exploration.

Workflow Run Sandboxes

Created automatically when a workflow run executes. Each step in the pipeline (designer, checker, optimizer) gets its own sandbox. These sandboxes are managed by the workflow orchestrator -- you typically monitor them through the run detail view rather than the sandboxes page.

Issue Session Sandboxes

Created during issue sessions. An issue session sandbox runs an AI agent that analyzes your repository, explores the codebase, and identifies problems and improvements. Issue session sandboxes operate independently of workflows.

Issue Session Sandboxes

Created during issue analysis sessions. These sandboxes run an AI agent that reviews your GitHub repository, identifies issues and improvements, and produces structured issue cards with suggested prompts.

Sandbox Configuration

Every sandbox is created with a configuration object that controls its resources and behavior:

• Template ID -- Which E2B template to use (e.g.,claude, opencode, codex,pi). Determines the pre-installed CLI tool and base environment.
• Timeout -- Maximum execution time, from 1 minute to 4 hours (60,000 to 14,400,000 milliseconds). If the sandbox exceeds this timeout, it is killed automatically.
• Memory -- RAM allocation in MB, between 256 MB and 8,192 MB. Higher memory is needed for large codebases and heavy compilation.
• CPU -- CPU count, between 1 and 8. More CPUs help with parallel builds and test execution.
• Designer Model -- The AI model to use for designer steps (e.g., claude-opus-4-6,claude-sonnet-4-6).
• Checker Model -- The AI model to use for checker steps (can differ from the designer model).
• Thinking Effort -- Per-model thinking effort settings (e.g., high, medium,low).

Relationship to Other Features

Sandboxes are connected to nearly every feature in CodeCourier:

• Workflows use sandboxes to execute each step.
• Personas define the agent configuration injected into sandboxes during workflow runs.
• Issue sessions run inside dedicated sandboxes.
• Learnings are extracted from sandbox message history after completion.
• Pull requests are created from sandbox branch state when a sandbox finishes work.
• Usage tracking records the cost of every sandbox session (E2B compute, AI token usage).