Working with Files

Understand the sandbox file system in CodeCourier -- file layout, project files, Git integration, and file persistence.

5 min read
sandboxesfilesfilesystem

Every CodeCourier sandbox runs a full Linux file system inside an E2B micro-VM. This file system is the workspace where AI agents read code, write files, install packages, and build projects. Understanding the file layout and how files persist across sandbox sessions is essential for working effectively with CodeCourier.

File System Layout

When a sandbox starts, it has a standard Linux directory structure. The key directories for AI agent work are:

Standard sandbox file layout
/home/user/                    # Home directory (agent working dir)
  project/                     # Cloned Git repository (if configured)
    .claude/                   # Claude Code configuration
      skills/                  # Injected skill files
      commands/                # Injected command files
    CLAUDE.md                  # Project instructions for Claude Code
    .system-prompt.txt         # System prompt file
    package.json               # Project package manifest
    ...                        # All other project files
  .env                         # Environment variables (if configured)
/tmp/                          # Temporary files
/usr/local/                    # Globally installed tools (Node.js, Python, etc.)

Home Directory

The default working directory is /home/user. When no Git repository is configured, the AI agent works directly in this directory. All CLI tools are configured to use this as the base path.

Project Directory

When a GitHub repository URL is configured (either from project settings or per-sandbox), the repository is cloned into /home/user/project. The agent's working directory is set to this path. All git operations (branch creation, commits, pushes) happen within this directory.

Git Integration

Git is a first-class citizen in CodeCourier sandboxes. When a sandbox is created with a GitHub repository URL, the setup sequence handles the full Git workflow automatically.

Repository Cloning

During sandbox setup, CodeCourier clones the configured repository into /home/user/project. If a GitHub personal access token is available (from the project's API keys), it is used for authentication, enabling access to private repositories.

Branch Management

For workflow runs and sprint chains, CodeCourier creates a feature branch automatically. The branch name is typically generated from the task description. For standalone sandboxes, the agent works on whatever branch is checked out after cloning (usually main ormaster), but the agent itself may create branches as part of its work.

Credential Helper

If a GitHub token is available, CodeCourier configures a Git credential helper inside the sandbox. This allows the AI agent to push commits to the remote repository without being prompted for credentials. The credential helper is set up using git config commands during the sandbox setup phase.

Git credential setup (simplified)
# CodeCourier configures this automatically
git config --global credential.helper store
echo "https://oauth2:${GITHUB_TOKEN}@github.com" > ~/.git-credentials

# Git user identity for commits
git config --global user.name "CodeCourier Agent"
git config --global user.email "agent@codecourier.dev"

Custom Git Identity

You can configure custom Git commit name and email in Project Settings. These values override the default agent identity for all commits made inside sandboxes for that project.

Automatic Commit and Push

When a sandbox finishes work or is killed, CodeCourier performs a safety-net commit and push. This ensures that any uncommitted changes the agent made are not lost when the VM is destroyed:

  1. Stage all changes with git add -A.
  2. Check if there are staged changes with git diff --cached --quiet.
  3. Commit with an auto-generated message if changes exist.
  4. Push the branch to the remote.

This is a best-effort operation -- if it fails (e.g., no remote configured), the sandbox termination continues normally.

Configuration Files

During sandbox setup, CodeCourier writes several configuration files into the file system. These files control the AI agent's behavior.

System Prompt

The system prompt is written to /home/user/.system-prompt.txt(or a similar path depending on the tool). The AI CLI reads this file at startup to set the system-level instructions for the agent. The system prompt comes from the project settings or the default template.

CLAUDE.md

For tools that support it (Claude Code and Pi), a CLAUDE.mdfile is written to the project directory. This file contains project-specific instructions, coding standards, and context that the agent uses throughout its session. The content comes from the project settings' claudeMd field.

Skills and Commands

Claude Code sandboxes receive injected skills and commands. These are written to the .claude/skills/ and .claude/commands/ directories within the project folder. Each skill is a collection of files (typically a SKILL.mdand reference files), and each command is a markdown file with instructions.

Only the skills and commands enabled in the project settings are injected. This keeps the context window focused on relevant knowledge.

Scripts

User-defined scripts can also be injected into the sandbox. Scripts are written to the file system and are available for the agent to execute. This is useful for custom build scripts, test runners, or deployment commands.

Compiled Learnings

If the project has compiled learnings (from previous sandbox sessions that were reviewed and approved), they are written into the sandbox as a markdown file. The agent can reference these learnings to avoid repeating mistakes and to follow established patterns.

Environment Variables

Project-level environment variables are injected into the sandbox environment during setup. These are available to the AI agent and any processes it spawns. Environment variables are configured in Project Settings and can be marked as secret (displayed masked in the UI).

In addition to user-configured variables, CodeCourier injects several system variables:

  • Provider API keys -- The API keys for the configured CLI tool provider (e.g., ANTHROPIC_API_KEY,OPENROUTER_API_KEY).
  • GitHub token -- As GITHUB_TOKEN for Git operations.
  • Convex keys -- Deploy and dev keys for Convex projects (if configured).
  • Test credentials -- Test user email and password for E2E testing (if configured).

Secret Handling

API keys and secrets are fetched server-side through internal Convex queries and injected directly into the sandbox environment. They are never exposed to the client-side UI or stored in the sandbox configuration object. The encrypted keys in the database are decrypted only at the moment of sandbox creation.

File Persistence

Sandbox file systems are ephemeral. When a sandbox is killed or its timeout expires, the E2B virtual machine is destroyed and all files are lost. There are two mechanisms for preserving work:

Git Push

The primary persistence mechanism is Git. Code committed and pushed to the remote repository survives sandbox termination. This is why CodeCourier performs a safety-net commit and push when sandboxes terminate -- it ensures that the agent's work is not lost.

Pull Request Artifacts

When a pull request is created from sandbox work, it serves as a durable record of what the agent produced. The PR includes all committed changes and can be reviewed, merged, or discarded through standard GitHub workflows.

No Built-in File Download

CodeCourier does not currently provide a file download mechanism for arbitrary sandbox files. If you need to preserve files that are not in a Git repository, ensure the agent commits them or outputs their contents in the terminal before the sandbox terminates.

Dependency Installation

AI agents commonly install dependencies as part of their work. The sandbox templates come with Node.js and npm pre-installed, and the setup sequence can run package installation automatically. CodeCourier includes a npmInstallWithRetry utility that handles transient npm registry failures by retrying the install command.

Dependencies installed during a sandbox session are local to that sandbox. They do not persist across sessions unless they are committed to the repository (e.g., by updating package.json andpackage-lock.json).