Skip to main content

​
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

​
Introduction

When you create an OpenReward Sandbox, 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:
ImageDescriptionUse Case
generalreasoning/python-ds:3.12-toolsPython 3.12 with data science libraries (pandas, numpy, etc.)Data analysis, file processing, general Python tasks
generalreasoning/knowledge-workerDocument processing support (PDF, Excel, Word, PowerPoint)Environments using pre-built 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. 
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 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. 
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 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:
ImageUse Case
python:3.11-slimMinimal Python environment
python:3.12Full Python with build tools
node:20Node.js environments
ubuntu:22.04General-purpose Linux
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: 
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: 
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. 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: 
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: 
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: 
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: 
docker run --platform linux/amd64 -it yourusername/my-sandbox-image:latest bash

​
Next Steps

Sandboxes

Learn more about sandbox configuration, lifecycle, and machine sizes

Building Agentic Environments

Build a complete agentic environment using sandbox Docker images

Using Toolsets

Use the knowledge-worker image with pre-built document processing toolsets