# Setting Up a Docker Sandbox with GPU Passthrough for AutoResearchClaw: Complete Configuration Guide

> Accelerate AutoResearchClaw experiments with GPU passthrough in Docker. This guide shows configuration for NVIDIA Container Toolkit and effortless GPU integration.

- Repository: [AIMING Lab/AutoResearchClaw](https://github.com/aiming-lab/AutoResearchClaw)
- Tags: how-to-guide
- Published: 2026-05-28

---

**Enable GPU-accelerated experiments in AutoResearchClaw by setting `gpu_enabled: true` in `DockerSandboxConfig`, which automatically detects NVIDIA Container Toolkit and injects `--gpus` flags into the container runtime.**

AutoResearchClaw can execute the experiment stage of its 23-stage research pipeline inside an isolated Docker container. Setting up a Docker sandbox with GPU passthrough for AutoResearchClaw allows heavy-weight deep-learning workloads to run on the host’s NVIDIA GPUs while keeping the rest of the pipeline safe from side effects and dependency conflicts.

## Architecture Overview

The sandbox implementation centers on three core components that handle container lifecycle and GPU allocation.

### DockerSandbox Class

The **`DockerSandbox`** class in [`researchclaw/experiment/docker_sandbox.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/experiment/docker_sandbox.py) orchestrates experiment execution. It manages a three-phase lifecycle:

1. **Dependency installation** via `pip install`
2. **Optional setup** via [`setup.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/setup.py) 
3. **Experiment entry point** execution

The class builds the final `docker run` command, injects the experiment harness template, and ensures container cleanup after execution.

### Configuration Dataclass

**`DockerSandboxConfig`** in [`researchclaw/config.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/config.py) (lines 61-73) defines all user-configurable options:

- `image`: Base Docker image (e.g., `researchclaw/experiment:latest`)
- `gpu_enabled`: Boolean flag to activate GPU passthrough
- `gpu_device_ids`: List of specific GPU indices to expose (empty list exposes all)
- `memory_limit_mb`: RAM constraint for the container
- `network_policy`: Network access rules (`setup_only`, `none`, or `full`)
- `shm_size_mb`: Shared memory allocation for large tensors

### Experiment Harness

The **[`harness_template.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/harness_template.py)** file in [`researchclaw/experiment/harness_template.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/experiment/harness_template.py) provides a minimal Python stub injected into every container. This ensures the experiment API (`run_experiment`, metrics collection) remains identical between local and Docker execution modes.

## GPU Passthrough Mechanics

GPU support relies on runtime detection and CLI flag assembly within the `DockerSandbox` class.

### Runtime Detection

The `check_nvidia_runtime()` method (lines 221-233 in [`researchclaw/experiment/docker_sandbox.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/experiment/docker_sandbox.py)) validates NVIDIA Container Toolkit availability by running a test container:

```python

# Simplified logic from check_nvidia_runtime()

docker run --gpus all nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04 nvidia-smi

```

If this command succeeds, the host supports GPU passthrough.

### Command Assembly

The `_build_run_command()` method (lines 82-106, 68-76, 68-84) constructs the Docker CLI list. When `cfg.gpu_enabled` is `True`:

- **Specific GPUs**: If `gpu_device_ids` is non-empty, adds `--gpus device=0,1,...`
- **All GPUs**: If the list is empty, adds `--gpus all`

The method also applies user mapping (`--user $(id -u):$(id -g)`) on POSIX systems to ensure GPU-generated output files maintain correct ownership in bind-mounted directories.

## Configuration Steps

Enable Docker mode and GPU passthrough via your [`config.arc.yaml`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/config.arc.yaml) or [`config.yaml`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/config.yaml) file:

```yaml
experiment:
  mode: docker                # Switch pipeline to DockerSandbox

  docker:
    image: "researchclaw/experiment:latest"
    gpu_enabled: true        # Activate GPU passthrough

    gpu_device_ids: []       # Empty exposes all GPUs; use [0,1] for specific devices

    memory_limit_mb: 16384   # 16 GB RAM limit

    network_policy: "setup_only"   # Network for pip/setup only

    pip_pre_install: ["torch", "torchvision"]
    auto_install_deps: true
    shm_size_mb: 4096        # Critical for large CUDA tensors

    keep_containers: false   # Set true for debugging

```

The default configuration already enables `gpu_enabled: true` and `network_policy: "setup_only"`, which is sufficient for most research workflows.

## Running Docker-Backed Experiments

Once configured, use the standard CLI workflow:

```bash

# Initialize configuration

researchclaw init

# Run with Docker mode (GPU enabled via config)

researchclaw run --topic "Zero-Shot Image Classification with Vision Transformers"

```

You can also force Docker mode via CLI flag regardless of config settings:

```bash
researchclaw run --topic "Your Research Topic" --mode docker

```

### Manual Sandbox Invocation

To inspect the generated Docker command or debug execution, invoke the sandbox directly via Python:

```python
from pathlib import Path
from researchclaw.config import DockerSandboxConfig
from researchclaw.experiment.docker_sandbox import DockerSandbox

cfg = DockerSandboxConfig(
    image="researchclaw/experiment:latest",
    gpu_enabled=True,
    memory_limit_mb=8192,
    network_policy="setup_only",
)

sandbox = DockerSandbox(cfg, workdir=Path("/tmp/rc-sandbox"))

# Build and print the command

cmd = sandbox._build_run_command(
    staging_dir=Path("/tmp/rc-sandbox/project"),
    entry_point="train.py",
    container_name="rc-debug-001",
    entry_args=None,
    env_overrides=None,
)

print("Generated command:", " ".join(cmd))

```

This outputs a command structure similar to:

```bash
docker run --name rc-debug-001 --rm \
  -v /tmp/rc-sandbox/project:/workspace \
  -w /workspace \
  --memory=8192m --shm-size=2048m \
  --gpus all \
  researchclaw/experiment:latest \
  train.py

```

## Troubleshooting GPU and Container Issues

| Issue | Symptom | Solution |
|-------|---------|----------|
| **Missing NVIDIA runtime** | `check_nvidia_runtime()` returns `False`; GPUs invisible inside container | Install NVIDIA Container Toolkit and verify with `docker run --gpus all nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04 nvidia-smi` |
| **CUDA Out of Memory** | Experiments crash despite host VRAM availability | Increase `memory_limit_mb` and `shm_size_mb` (e.g., `shm_size_mb: 4096`) |
| **Network blocked during dataset download** | Connection errors in experiment phase | Change `network_policy` to `"full"` if runtime downloads are required, or pre-download datasets during setup |
| **Permission denied on output files** | Files owned by root in mounted volumes | On POSIX systems, the sandbox automatically adds `--user $(id -u):$(id -g)`; on Windows, ensure your Dockerfile defines a non-root user |

## Summary

- **Core Implementation**: The `DockerSandbox` class in [`researchclaw/experiment/docker_sandbox.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/experiment/docker_sandbox.py) handles container lifecycle, GPU flag injection, and three-phase experiment execution.
- **GPU Activation**: Set `gpu_enabled: true` in `DockerSandboxConfig`; the system auto-detects NVIDIA Container Toolkit and appends `--gpus` flags accordingly.
- **Network Security**: Use `setup_only` (default) to allow package installation but block network access during actual experiment execution.
- **Resource Management**: Configure `shm_size_mb` generously for GPU workloads, and use `gpu_device_ids` to pin specific GPUs rather than exposing all hardware.

## Frequently Asked Questions

### How do I restrict AutoResearchClaw to use only specific GPUs?

Set the `gpu_device_ids` configuration option to a list of device indices. In [`config.arc.yaml`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/config.arc.yaml), specify `gpu_device_ids: [0, 2]` to expose only GPU 0 and GPU 2 to the container, rather than using `--gpus all`.

### What NVIDIA Container Toolkit version is required for GPU passthrough?

The sandbox uses standard Docker `--gpus` flag syntax, requiring NVIDIA Container Toolkit 2.0 or later. The `check_nvidia_runtime()` method specifically validates against the `nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04` image, but any recent CUDA base image works if the toolkit is properly installed on the host.

### Why does my experiment fail with shared memory errors despite having free GPU memory?

PyTorch and TensorFlow use host shared memory (`/dev/shm`) for inter-process communication and data loading. Increase the `shm_size_mb` parameter in your Docker configuration—values of 4096 MB or higher are recommended for large computer vision models.

### How can I debug a failed container that AutoResearchClaw automatically removed?

Set `keep_containers: true` in your Docker configuration before running the experiment. This prevents automatic container deletion, allowing you to inspect logs and state using `docker logs <container_name>` or `docker exec -it <container_name> /bin/bash` after the failure occurs.