> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Environments

> Add dependencies to your agents with Docker 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:**

```bash theme={null}
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

```dockerfile theme={null}
FROM e2bdev/code-interpreter:latest
RUN pip install numpy pandas scikit-learn --no-cache-dir
```

Publish with the `--docker` flag:

```bash theme={null}
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.

<Note>
  You don't need Docker installed locally. The platform handles all building.
</Note>

### Dockerfile Guidelines

**Base image** (required):

```dockerfile theme={null}
FROM e2bdev/code-interpreter:latest
```

**What works:**

```dockerfile theme={null}
# 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:**

```dockerfile theme={null}
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
```

<Warning>
  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.
</Warning>

### Example: Video Processing Agent

```dockerfile theme={null}
FROM e2bdev/code-interpreter:latest
RUN pip install ffmpeg-python moviepy imageio-ffmpeg --no-cache-dir
```

<Tip>
  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.
</Tip>

***

## CLI Commands

```bash theme={null}
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:

1. **Agent-specific** — Dockerfile in bundle creates dedicated environment
2. **Workspace default** — Falls back to workspace's default environment
3. **Base image** — Uses E2B's base `code-interpreter` if neither set

<Note>
  **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.
</Note>

***

## Service Environments

[Always-on services](/using-agents/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).

<Note>
  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.
</Note>