Custom Environments

Agents with runtime.command (code runtime) or loop config (managed loop) run in E2B sandboxes. The platform automatically selects the right base image based on your agent’s entrypoint:

Entrypoint	Base Image	Includes
`.py` files	Python base	Python 3.11, pip
`.js` files	Node.js base	Node.js 20, npm, Python 3

JavaScript agents get a dedicated Node.js sandbox template with both Node.js and Python pre-installed. Dependencies from package.json are installed automatically via npm ci (when a lockfile is present) or npm install. Custom environments let you add dependencies beyond the defaults.

Predefined Environments

Four ready-to-use environments are available to all users:

Name	Packages
`python-ml`	numpy, pandas, scikit-learn, matplotlib, seaborn
`python-ffmpeg`	ffmpeg-python, moviepy, imageio-ffmpeg
`python-image`	pillow, opencv-python-headless
`python-scraping`	requests, beautifulsoup4, lxml, httpx

Set as Workspace Default

All agents in your workspace can use a default environment: Via CLI:

orch env list                        # Find environment ID
orch env set-default <environment-id>

Via Web UI: Settings → Workspace → Default Environment Agents without their own Dockerfile use this default.

Custom Environments

Need specific packages? Include a Dockerfile in your agent directory.

Quick Start

FROM e2bdev/code-interpreter:latest
RUN pip install numpy pandas scikit-learn --no-cache-dir

Publish with the --docker flag:

orch publish --docker

The platform builds your custom environment. First build takes 2-5 minutes; subsequent publishes with the same Dockerfile reuse the cached build.

You don’t need Docker installed locally. The platform handles all building.

Dockerfile Guidelines

Base image (required):

FROM e2bdev/code-interpreter:latest

What works:

# Python packages
RUN pip install package1 package2 --no-cache-dir

# System packages
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

# Environment variables
ENV MY_VAR=value

What doesn’t work:

COPY ./data /app   # Rejected - no build context available
ADD ./file /app    # Rejected - no build context available
EXPOSE 8080        # Rejected - sandboxes don't expose ports
ENTRYPOINT [...]   # Ignored - overridden by sandbox
CMD [...]          # Ignored - overridden by sandbox

COPY and ADD commands are rejected because Dockerfiles are built in isolation without access to your bundle files. Install dependencies via pip/apt instead, or download files at runtime in your agent code.

Example: Video Processing Agent

FROM e2bdev/code-interpreter:latest
RUN pip install ffmpeg-python moviepy imageio-ffmpeg --no-cache-dir

Prefer pip install over apt-get when possible. Many system packages (like ffmpeg) have pure-Python alternatives (like imageio-ffmpeg) that work better in cloud sandboxes.

CLI Commands

orch env list                          # List available environments
orch env status <id>                   # Check build status
orch env create -f Dockerfile -n name  # Create from Dockerfile
orch env delete <id>                   # Delete (if no agents use it)
orch env set-default <id>              # Set workspace default
orch env clear-default                 # Clear workspace default

Environment Priority

When running an agent in a sandbox:

Agent-specific — Dockerfile in bundle creates dedicated environment
Workspace default — Falls back to workspace’s default environment
Base image — Uses E2B’s base code-interpreter if neither set

Dynamic workspace defaults: Changing your workspace default immediately affects all agents that don’t have their own Dockerfile. Existing agents without agent-specific environments will use the new default on their next run.

Service Environments

Always-on services use a different runtime from on-demand runs:

	On-demand (`orch run`)	Always-on (`orch service deploy`)
Runtime	E2B sandbox	Cloud Run container
Base image	`e2bdev/code-interpreter`	Service runner (Python 3.11 + Node.js 20)
Dependencies	Installed per run	Installed once at deploy time
Custom Dockerfile	Yes (`orch publish --docker`)	Not yet supported
Entrypoint	Platform-managed	Auto-detected or `--command` flag

Service dependencies are installed from your requirements.txt or package.json during deployment. The service runner pre-installs common tools (pip, npm, git).

Custom Dockerfiles are not yet supported for services. If your service needs system packages beyond the defaults, use a run_command in your manifest that installs them at startup.

Get Started

Using Agents

Building Agents

Guides

Concepts

API Reference

Custom Environments

Predefined Environments

Set as Workspace Default

Custom Environments

Quick Start

Dockerfile Guidelines

Example: Video Processing Agent

CLI Commands

Environment Priority

Service Environments

​Predefined Environments

​Set as Workspace Default

​Custom Environments

​Quick Start

​Dockerfile Guidelines

​Example: Video Processing Agent

​CLI Commands

​Environment Priority

​Service Environments

Predefined Environments

Set as Workspace Default

Custom Environments

Quick Start

Dockerfile Guidelines

Example: Video Processing Agent

CLI Commands

Environment Priority

Service Environments