Sandbox Templates

Understand E2B sandbox templates in CodeCourier -- built-in tool templates, custom templates, and template management.

5 min read
sandboxestemplatese2b

Sandbox templates define the base environment for AI coding agents. Each template is a pre-built E2B image containing a specific CLI tool, its dependencies, and a standard set of development tools. When CodeCourier creates a sandbox, it selects a template based on the configured CLI tool and uses it to provision the virtual machine.

What is a Template?

An E2B template is a snapshot of a Linux environment that serves as the starting point for every sandbox. Templates are identified by a string ID (e.g., claude, opencode) and are stored in E2B's infrastructure. When a sandbox is created, E2B provisions a new micro-VM from the template image, giving the sandbox a complete file system, installed packages, and configured tools from the template.

Templates solve a critical performance problem: instead of installing CLI tools and dependencies from scratch every time a sandbox starts, the template provides everything pre-installed. This reduces sandbox startup time from minutes to seconds.

Built-in Templates

CodeCourier ships with templates for each supported CLI tool. The tool registry in convex/config/tools.config.ts defines the template configuration for each tool.

Claude Code Template

  • Template ID: claude
  • Custom Tag: claude-custom
  • Default Timeout: 15 minutes (900,000 ms)
  • Default Memory: 1,024 MB
  • Default CPUs: 2
  • Provider: Anthropic
  • Pre-installed: Claude Code CLI (@anthropic-ai/claude-code), Node.js, Python, Git

The Claude Code template is the most fully featured. It supports streaming JSON output, CLAUDE.md project files, skill injection, command injection, learning compilation, and thinking effort control. This is the default template for most operations.

OpenCode Template

  • Template ID: opencode
  • Provider: OpenRouter
  • Pre-installed: OpenCode CLI, Node.js, Git

The OpenCode template supports OpenRouter-backed models including Gemini models. It uses a config-file based system prompt approach rather than CLAUDE.md.

Codex Template

  • Template ID: codex
  • Provider: OpenAI
  • Pre-installed: Codex CLI, Node.js, Git

The Codex template runs OpenAI's autonomous coding agent. It uses GPT-5.4 family models and provides text-format output.

Pi Template

  • Template ID: pi
  • Provider: OpenRouter
  • Pre-installed: Pi CLI, Node.js, Git

The Pi template provides an open-source coding agent with CLAUDE.md compatibility. It reads CLAUDE.md files the same way Claude Code does, making it easy to switch between tools.

Template Capabilities

Not all templates support the same features. The tool registry defines a capabilities object for each tool that CodeCourier uses to determine which features are available:

Tool capability flags
{
  supportsStreaming: true,      // Real-time output streaming
  supportsChecker: true,        // Can act as checker in workflows
  supportsIssueSessions: true,  // Can run issue sessions
  supportsInteractiveMode: true,// Supports follow-up messages
  supportsCustomSystemPrompt: true,
  supportsCustomClaudeMd: true, // CLAUDE.md file support
  supportsSkillInjection: true, // .claude/skills/ injection
  supportsLearnings: true,      // Learning extraction
  outputFormat: 'stream-json',  // Output format type
}

These capabilities influence the UI -- for example, if a tool does not support skill injection, the skills selector is hidden when that tool is chosen. If a tool does not support streaming, the terminal view falls back to polling mode.

Custom Templates

For advanced use cases, you can build and use custom E2B templates. Custom templates let you pre-install additional tools, configure specific system packages, or set up custom development environments.

Building a Custom Template

E2B provides a template builder that takes a Dockerfile-like specification and produces a template. The general process:

  1. Define your base environment in an E2B template configuration file.
  2. Include all tools and packages your agents need.
  3. Build the template using the E2B CLI or API.
  4. Note the template ID returned by E2B.

Using a Custom Template

To use a custom template in CodeCourier, specify it as thetemplateId in the sandbox configuration. CodeCourier constructs the custom tag using the buildCustomTagfunction from the tool registry, which combines the tool ID with a custom suffix.

Template Caching

E2B caches templates at the infrastructure level. Once a template is built, subsequent sandbox launches from that template are fast because the image is already available. Rebuild only when your base environment needs to change.

Template Build Tracking

CodeCourier tracks template builds in the templateBuildstable. Each build record contains:

  • Tool ID -- Which CLI tool the template is for.
  • Template Name -- The E2B template name.
  • CLI Version -- The CLI tool version installed in the template.
  • Status -- building, success, or failed.
  • Triggered By -- Who initiated the build.
  • Timestamps -- Start and completion times.

This tracking ensures you can monitor template build progress and debug failures. Template builds are indexed by tool ID and status for efficient querying.

Version Management

CLI tools are updated regularly. When a new version of Claude Code, OpenCode, or Codex is released, the corresponding template needs to be rebuilt to include the updated CLI. CodeCourier's install commands use the @latest tag to always get the newest version:

Template CLI install commands
# Claude Code
npm install -g @anthropic-ai/claude-code@latest

# OpenCode
npm install -g @anthropic-ai/opencode@latest

# Codex
npm install -g @openai/codex@latest

After a template rebuild, sandbox records store the CLI version that was detected during setup. This allows you to track which version of the tool was used for any given sandbox session.