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

# Docker Images

> Choose and configure Docker images for sandbox environments

## Goals

* Understand the pre-made Docker images available for OpenReward sandboxes
* Use any public Docker Hub image in a sandbox environment
* Build and push custom Docker images for specialized needs
* Configure the `image` field in `SandboxSettings` for different use cases

## Prerequisites

* An OpenReward [account](https://openreward.ai/)
* An OpenReward [API key](https://openreward.ai/keys)
* [Docker](https://docs.docker.com/get-docker/) installed locally (for custom images)
* Completion of the [Building Agentic Environments](/environments/building-agentic-environments) tutorial

## Introduction

When you create an [OpenReward Sandbox](/concepts/sandboxes), the `image` field in `SandboxSettings` determines what software, libraries, and runtimes are available inside the container. Picking the right image means your agent has the tools it needs without installing packages at runtime.

OpenReward provides pre-made images for common use cases, but you can also use any public image from Docker Hub, or build and push your own. This page covers all three options and how they connect to your `SandboxSettings` configuration.

**Note**: OpenReward's sandbox infrastructure runs on `linux/amd64`. If you're building custom images on an ARM machine (e.g. Apple Silicon), you'll need to target this platform explicitly — more on this below.

## Pre-Made Images

We maintain two images that cover the most common agentic workloads:

| Image                                   | Description                                                   | Use Case                                                              |
| --------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |
| `generalreasoning/python-ds:3.12-tools` | Python 3.12 with data science libraries (pandas, numpy, etc.) | Data analysis, file processing, general Python tasks                  |
| `generalreasoning/knowledge-worker`     | Document processing support (PDF, Excel, Word, PowerPoint)    | Environments using pre-built [Toolsets](/environments/using-toolsets) |

### `generalreasoning/python-ds:3.12-tools`

This is the default image used by the `orwd init --template sandbox` scaffold. It includes Python 3.12, pip, and core data science libraries like pandas and numpy. Use this when your agent needs to write and execute Python code for data analysis, file manipulation, or general-purpose tasks.

```python theme={null}
from openreward import AsyncOpenReward, SandboxSettings, SandboxBucketConfig

self.sandbox_settings = SandboxSettings(
    environment="YourUsername/AccountantEnv",
    image="generalreasoning/python-ds:3.12-tools",
    machine_size="0.5:1",
    block_network=False,
    bucket_config=SandboxBucketConfig(
        mount_path="/tmp/sandbox/",
        read_only=True,
    )
)

or_client = AsyncOpenReward(api_key=secrets.get("api_key"))
self.sandbox = or_client.sandbox(self.sandbox_settings)
```

See the [Building Agentic Environments](/environments/building-agentic-environments) tutorial for a full walkthrough using this image.

### `generalreasoning/knowledge-worker`

This image includes all the dependencies needed for the pre-built toolsets: pdfplumber, pypdf, reportlab, pdf2image, python-docx, openpyxl, and python-pptx. If your environment uses `PDFToolset`, `ExcelToolset`, `WordToolset`, or `PowerPointToolset`, this is the image to use.

```python theme={null}
from openreward import AsyncOpenReward, SandboxSettings

self.sandbox_settings = SandboxSettings(
    environment="YourUsername/DocProcessorEnv",
    image="generalreasoning/knowledge-worker",
    machine_size="0.5:1",
    block_network=False,
)

or_client = AsyncOpenReward(api_key=secrets.get("api_key"))
self.sandbox = or_client.sandbox(self.sandbox_settings)
```

See [Using Toolsets](/environments/using-toolsets) for a full guide on composing toolsets with this image.

## Using Any Docker Hub Image

The `image` field in `SandboxSettings` accepts any public Docker Hub image. This is useful when you need a specific language runtime, a minimal base image, or something outside the Python ecosystem entirely.

Some common options:

| Image              | Use Case                     |
| ------------------ | ---------------------------- |
| `python:3.11-slim` | Minimal Python environment   |
| `python:3.12`      | Full Python with build tools |
| `node:20`          | Node.js environments         |
| `ubuntu:22.04`     | General-purpose Linux        |

```python theme={null}
settings = SandboxSettings(
    environment="username/my-env",
    image="node:20",
    machine_size="1:2",
    block_network=False,
)
```

**Note**: Larger images take longer to pull on first sandbox creation. If startup time matters, prefer slim or minimal images when you don't need the full set of system packages.

## Building Custom Images

When the pre-made images don't include the dependencies you need, you can build your own image, push it to Docker Hub, and reference it in `SandboxSettings`.

### Writing a Dockerfile

Start with a base image and add your dependencies. Here's a complete example for a sandbox that needs specific ML libraries:

```dockerfile theme={null}
FROM python:3.12-slim

RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
```

With a `requirements.txt`:

```txt theme={null}
pandas==2.2.0
numpy==1.26.3
scikit-learn==1.4.0
matplotlib==3.8.2
```

**Important**: This Dockerfile is for your **sandbox image** — the container where the agent executes code. This is separate from the environment server Dockerfile used to [deploy your environment](/deployment/github-integration). The sandbox image is what gets specified in the `image` field of `SandboxSettings`.

### Building and Pushing

OpenReward's sandbox infrastructure runs on `linux/amd64`. You must target this platform when building, even if you're developing on an Apple Silicon Mac or another ARM machine:

```bash theme={null}
docker build --platform linux/amd64 -t yourusername/my-sandbox-image:latest .
```

**Important**: If you omit `--platform linux/amd64` and build on an ARM machine, the image will fail to run on OpenReward's infrastructure.

Once built, push to Docker Hub:

```bash theme={null}
docker login
docker push yourusername/my-sandbox-image:latest
```

The image must be publicly accessible on Docker Hub. OpenReward pulls images from public repositories.

### Using Your Custom Image

Once pushed, reference it in `SandboxSettings` just like any other image:

```python theme={null}
from openreward import AsyncOpenReward, SandboxSettings, SandboxBucketConfig
from openreward.environments import Environment, TextBlock, ToolOutput, tool
from pydantic import BaseModel


class BashParams(BaseModel):
    command: str


class CustomImageEnv(Environment):
    def __init__(self, task_spec, secrets):
        super().__init__(task_spec, secrets)

        self.sandbox_settings = SandboxSettings(
            environment="YourUsername/CustomImageEnv",
            image="yourusername/my-sandbox-image:latest",  # Your custom image
            machine_size="1:2",
            block_network=False,
            bucket_config=SandboxBucketConfig(
                mount_path="/workspace",
                read_only=True,
            ),
        )

        or_client = AsyncOpenReward(api_key=secrets.get("api_key"))
        self.sandbox = or_client.sandbox(self.sandbox_settings)

    async def setup(self):
        await self.sandbox.start()

    async def teardown(self):
        await self.sandbox.stop()

    @tool
    async def bash(self, params: BashParams) -> ToolOutput:
        """Execute a bash command in the sandbox."""
        output, code = await self.sandbox.run(params.command.strip())
        return ToolOutput(
            blocks=[TextBlock(text=f"{output}\n\n(exit {code})")],
            reward=0.0,
            finished=False,
        )
```

The only thing that changes compared to using a pre-made image is the `image` value — everything else in `SandboxSettings` works the same way.

## Best Practices

**Start with pre-made images**: Use `generalreasoning/python-ds:3.12-tools` or `generalreasoning/knowledge-worker` when they cover your needs. Only build custom images when you need dependencies they don't include.

**Keep images small**: Use slim base images, clean up after `apt-get install` with `rm -rf /var/lib/apt/lists/*`, and use `pip install --no-cache-dir`. Smaller images pull faster and your sandboxes start sooner.

**Always build for `linux/amd64`**: Use `docker build --platform linux/amd64` regardless of your local machine architecture.

**Pin dependency versions**: Use specific versions in `requirements.txt` (e.g. `pandas==2.2.0`) rather than unpinned packages. This ensures reproducible builds.

**Test locally before pushing**: Run your image locally to verify it has everything you need:

```bash theme={null}
docker run --platform linux/amd64 -it yourusername/my-sandbox-image:latest bash
```

## Next Steps

<Card title="Sandboxes" icon="cube" href="/concepts/sandboxes">
  Learn more about sandbox configuration, lifecycle, and machine sizes
</Card>

<Card title="Building Agentic Environments" icon="robot" href="/environments/building-agentic-environments">
  Build a complete agentic environment using sandbox Docker images
</Card>

<Card title="Using Toolsets" icon="toolbox" href="/environments/using-toolsets">
  Use the knowledge-worker image with pre-built document processing toolsets
</Card>