The Agentic Researcher

A Practical Guide to AI-Assisted Research in Mathematics and Machine Learning

Paper · Project Page · Quick Start · Workflow · Architecture · Citation

Max Zimmer · Nico Pelleriti · Christophe Roux · Sebastian Pokutta

IOL Lab · Zuse Institute Berlin & TU Berlin

---

The Agentic Researcher launches AI coding agents inside sandboxed containers with filesystem isolation, GPU support, and structured research instructions.

Supports Claude Code, OpenCode, Gemini CLI, Codex CLI, and pi.

Prerequisites

• Docker (default), Podman, or Apptainer (Linux only)
• An API key or OAuth login for your chosen CLI tool (see supported tools)
• GPU drivers installed on the host if you want GPU passthrough
• Project dependencies managed with uv (recommended) — the agent runs uv sync inside the sandbox

Quick Start

# 1. Clone the repository
git clone https://github.com/ZIB-IOL/The-Agentic-Researcher.git
cd The-Agentic-Researcher

# 2. Install
./scripts/install.sh

# 3a. Build container for Docker (default)
agentic-researcher --build

# 3b. Build container for Podman
agentic-researcher --podman --build

# 3c. Build container for Apptainer (Linux only)
agentic-researcher --apptainer --build

Docker is the default runtime when available. If Docker is not installed or not on PATH, but Podman is, the launcher and install script automatically fall back to Podman for OCI builds. Podman uses the same OCI image and launch flow as Docker, but runs through the podman CLI instead. When building with Podman, the build script requests Docker image format (podman build --format docker) so Dockerfile SHELL directives keep working and Podman avoids noisy OCI-format warnings. By default the launcher stores state under ~/.cache/agentic-researcher and launches Claude Code. Claude uses OAuth by default; other CLIs handle auth inside the tool, with standard API key env vars passed through if set.

Configuration

Run agentic-researcher --setup to create a configuration file at ${XDG_CONFIG_HOME:-$HOME/.config}/agentic-researcher/config.sh. The setup wizard lets you configure:

• Container runtime — Docker, Podman, or Apptainer
• CLI tool — Claude Code, OpenCode, Gemini CLI, Codex CLI, or pi
• Authentication — OAuth login or API key (with configurable env var name)
• Custom API endpoint — point Claude at an Anthropic-compatible proxy or gateway
• State/cache directory (AR_STATE_ROOT) — where caches, container /tmp, and tool state are stored. Defaults to ~/.cache/agentic-researcher. On HPC systems with Apptainer, set this to a path with sufficient space (e.g. on a scratch filesystem) to avoid hitting the default 64 MB overlay limit
• Extra environment variables (AR_EXTRA_ENV) — pipe-separated KEY=VALUE pairs forwarded into the container (e.g. HF_TOKEN=hf_...|WANDB_API_KEY=...)
• Network proxy — HTTP/HTTPS proxy settings for use inside the container
• Extra bind directories — additional host paths to mount into the sandbox

You can re-run --setup at any time to update your configuration.