E2B Sandboxes

E2B (short for "Environment to Bot") is the cloud sandbox provider that powers all code execution in CodeCourier. Every time an AI coding agent runs a task -- whether through a standalone sandbox, a workflow run, or an issue discovery session -- it does so inside an E2B micro-VM. This page explains what E2B provides, how CodeCourier integrates with it, configuration options, and troubleshooting common issues.

What E2B Provides

E2B offers on-demand isolated cloud virtual machines designed specifically for AI agent workloads. Unlike containers, E2B sandboxes are full micro-VMs with their own Linux kernel, providing stronger isolation guarantees. Key capabilities include:

• Full Linux environment -- Each sandbox runs a complete Linux system with a file system, network stack, and process execution capabilities.
• Template-based provisioning -- Sandboxes are created from pre-built templates that include common development tools (Node.js, Python, Git, etc.). Custom templates can be built with additional tools and configurations.
• Sub-second startup -- E2B micro-VMs boot in under a second, making them practical for on-demand use.
• Pause and resume -- Sandboxes can be paused to save resources and resumed later with their full state intact.
• Automatic cleanup -- Sandboxes have configurable timeouts and are automatically destroyed when they expire, preventing resource leaks.
• Network access -- Sandboxes can access the internet for installing packages, cloning repositories, and communicating with APIs.

How CodeCourier Uses E2B

Sandbox Provisioning

When a sandbox is created (either by a user from the dashboard or by a Trigger.dev task during a workflow run), CodeCourier calls the E2B SDK to provision a new micro-VM. The provisioning process follows these steps:

1. Template selection. The system selects a sandbox template based on the CLI tool configuration. Custom templates can be specified, or the default template for the chosen CLI tool is used (e.g., a claude template for Claude Code sandboxes).
2. Environment configuration. Environment variables are injected into the sandbox, including API keys (Anthropic, OpenRouter, OpenAI, GitHub), project settings, system prompts, and skill files.
3. VM creation. The E2B SDK's Sandbox.create() method is called with the template name and configuration options including timeout duration.
4. Agent initialization. After the VM is running, the CLI tool is launched inside it and the initial prompt (if any) is sent to the agent.

Lifecycle Management

CodeCourier tracks sandbox state through the following lifecycle:

• "creating" -- E2B is provisioning the VM. The Convex record exists but the VM is not yet ready.
• "running" -- The VM is active and the AI agent is executing.
• "paused" -- The VM has been paused to save resources. It can be resumed.
• "killed" -- The VM has been terminated. This is the final state for successfully completed sandboxes.
• "error" -- An error occurred during provisioning or execution.

Communication Pattern

CodeCourier communicates with E2B sandboxes through a process execution model. The Trigger.dev task running in the orchestration layer uses the E2B SDK to execute commands inside the sandbox, read output streams, and manage the sandbox file system. Messages between the user and the AI agent flow through Convex (stored in the sandboxMessages table) and are relayed to the sandbox by the Trigger.dev task.

E2B API Key Setup

To use E2B sandboxes, you need an E2B API key. This key is provided by each user or project, not at the server level.

Getting an E2B API Key

1. Create an account at e2b.dev.
2. Navigate to the API Keys section in your E2B dashboard.
3. Generate a new API key.
4. In CodeCourier, go to your project settings or user preferences and add the key under the E2B provider section.

Key Storage

E2B API keys are encrypted before storage in the Convex database. Only the last four characters are stored in plaintext for display purposes (e.g., ****abcd). Keys can be set at two levels:

• User level -- Stored in the apiKeys table. Applies to all projects unless overridden.
• Project level -- Stored in the projectProviderKeys table. Takes precedence over user-level keys.

Configuration Options

When creating a sandbox, the following E2B-related configuration options are available through the sandbox config object:

• Template -- The E2B template to use for the sandbox. Templates define the base system image, pre-installed tools, and default configuration.
• Timeout -- How long the sandbox stays alive before being automatically terminated. Measured in seconds.
• CLI Tool -- Which AI coding CLI to run inside the sandbox (Claude Code, OpenCode, Codex, etc.). This determines which template is selected if a custom template is not specified.
• Environment Variables -- Custom environment variables injected into the sandbox at creation time. These can include project-specific settings, deploy keys, and test credentials.

Custom Templates

CodeCourier supports custom E2B templates for specialized workloads. Custom templates are useful when you need:

• Additional system packages beyond the default template
• Pre-installed frameworks or language runtimes
• Custom system configurations or dotfiles
• Specific CLI tool versions

Template builds are tracked in the templateBuilds table, which records the tool ID, template name, CLI version, build status, and any errors. The dashboard shows build progress and allows you to select successful templates when creating sandboxes.

Cost Considerations

E2B charges based on sandbox uptime. Each running sandbox consumes resources regardless of whether the AI agent is actively executing. To optimize costs:

• Set appropriate timeouts to prevent forgotten sandboxes from running indefinitely.
• Use the "Kill All Sandboxes" action to clean up when you are done working.
• Monitor sandbox runtime in the usage dashboard (see Usage Tracking).
• For iterative workflows, the designer-checker pattern reuses the same sandbox across iterations rather than creating new ones.

Troubleshooting

Sandbox fails to create

• Check your E2B API key. Ensure it is valid and not expired. Try generating a new key in the E2B dashboard.
• Verify template availability. If you are using a custom template, ensure it has been successfully built.
• Check E2B service status. Visit the E2B status page to confirm the service is operational.

Sandbox times out prematurely

• Increase the timeout setting in your sandbox or workflow configuration. The default may be too short for complex tasks.

Agent cannot access the internet

• E2B sandboxes have internet access by default. If package installation fails, check that the package registry is accessible and that DNS resolution is working inside the sandbox.

API key errors inside sandbox

• Ensure the required provider keys (Anthropic, GitHub, etc.) are configured in your project settings. Missing keys will cause the AI coding CLI to fail at startup.
• Check that project-level keys are set for the correct project. User-level keys may not apply if a project-level key (even an invalid one) exists.