Creating Sandboxes

Creating a sandbox in CodeCourier provisions an isolated cloud Linux environment where an AI coding agent can work on your behalf. This guide covers how to launch sandboxes from the dashboard UI, the configuration options available, and how sandboxes are created programmatically during workflow runs.

Launching from the Dashboard

The primary way to create a standalone sandbox is through the Sandboxes page in your project dashboard. The launch dialog lets you configure every aspect of the sandbox before it is created.

Configuration Options in Detail

Template Selection

The template ID determines the base E2B image used for the sandbox. Each CLI tool has its own template with the tool pre-installed. CodeCourier also supports custom E2B templates -- if you have built a custom template with additional tools or dependencies, you can specify its ID. When a custom template is specified, CodeCourier uses thebuildCustomTag function to construct the E2B tag.

Thinking Effort

For Claude Code sandboxes, you can configure thinking effort on a per-model basis. This is passed as the --effort flag to the Claude CLI. Options are high, medium,low, or none. Higher thinking effort produces more thorough reasoning but costs more tokens.

Checker Template

Workflow sandboxes support a separate checkerTemplateIdthat allows the checker step to use a different E2B template than the designer step. If not set, the checker falls back to the main template.

CLI-Specific Overrides

The sandbox configuration supports per-step CLI tool overrides:

• designerCliId -- Override the CLI tool for designer steps.
• optimizerCliId -- Override the CLI tool for optimizer steps.
• checkerCliId -- Override the CLI tool for checker steps.

This allows a workflow to use Claude Code for design work and OpenCode for checking, for example.

Sandbox Setup Sequence

When a sandbox is created, CodeCourier runs a multi-phase setup sequence before the AI agent starts working. This setup is handled by thesetupSandboxForTool function and consists of:

Common Setup (All Tools)

1. Git clone -- If a GitHub repo URL is configured, the repo is cloned into /home/user/project. A new feature branch is created for the sandbox's work.
2. Git credential helper -- If a GitHub token is available, a credential helper is configured so the agent can push commits.
3. Environment variables-- Project-level environment variables are injected into the sandbox's shell environment.
4. System prompt -- The system prompt (from project settings or the default) is written to a file that the AI CLI reads.

Tool-Specific Setup

Each CLI tool has additional setup steps:

• Claude Code -- Writes CLAUDE.md to the project directory, injects skills and commands into .claude/skills/ and .claude/commands/, writes compiled learnings, and sets up the Anthropic API key.
• OpenCode -- Writes the system prompt as a config file in the format OpenCode expects and sets up the OpenRouter API key.
• Codex -- Configures the OpenAI API key and installs the Codex CLI if not present in the template.
• Pi -- Sets up the OpenRouter API key and writes CLAUDE.md (Pi supports the CLAUDE.md format).

Programmatic Creation

Sandboxes are also created programmatically in several contexts:

Workflow Runs

When a workflow run executes, the Trigger.dev orchestrator creates sandboxes for each step. The sandbox configuration comes from the workflow's defaultConfig, potentially overridden by per-step persona settings. Each step gets its own sandbox with the appropriate CLI tool, model, and instructions.

Work Chains

Work chains execute a sequence of issues, each as a separate workflow run. Each run creates its own sandboxes, reusing the same branch to accumulate changes across issues.

Issue Sessions

Issue sessions create a single sandbox that runs an AI scanning agent. The session sandbox explores the repository, identifies problems and improvements, and produces a structured list of issues. The sandbox is linked to the issue session record via the sessionId field.

Issue Sessions

Issue analysis sessions create a sandbox that scans the repository for potential improvements. The sandbox is linked to the issue session via the issueSessionId field.

// Internal flow: how CodeCourier creates a sandbox
const sandboxId = await ctx.runMutation(internal.sandboxes.create, {
  userId: user._id,
  projectId: project._id,
  sandboxId: e2bSandboxId, // from E2B SDK
  status: "running",
  config: {
    templateId: "claude",
    timeoutMs: 900_000,
    memoryMb: 1024,
    cpuCount: 2,
  },
  createdAt: Date.now(),
});