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

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 orchestrates experiment execution. It manages a three-phase lifecycle:

1. Dependency installation via pip install
2. Optional setup via 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 (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 file in 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) validates NVIDIA Container Toolkit availability by running a test container:

# 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 or config.yaml file:

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:

# 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:

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:

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:

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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}