AI Docker Image

Für die ai- und ai-agent-Container wird ein separates Docker Image genutzt.

Dabei wird Claude Code im Dockerfile über NPM¹ installiert und steht anschließend als CLI im Container zur Verfügung.

Neben der Installation der Claude Code CLI wird zusätzliche Software für die Nutzung der Claude Code Sandbox installiert.

Claude Code CLI ist ein Terminal-basiertes Interface für Claude mit Code-Ausführung und Dateisystem-Zugriff.

• Interaktive Konversationen mit Claude direkt im Terminal
• Tools und MCP-Server Integration
• Direkter Zugriff auf Projektdateien
• Konfigurierbare Permissions und Sandbox-Einstellungen

Bei der Installation gibt es zwei gängige Ansätze: Installation als root- oder als node-User

Dockerfile

USER root

RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}

USER node

Hier erfolgt die Installation als root. Anschließend wird in den node-User gewechselt, sodass Claude Code zur Laufzeit nicht mit Root-Rechten ausgeführt wird.

In einem gehärteten Container erhöht dies die Integrität der global installierten CLI.

Vorteil:

Die installierten Dateien gehören root und sind damit für den node-User nicht veränderbar.

Hintergrund:

Ein möglicher Angriffspunkt ohne diese Einschränkung wäre, dass kompromittierter Anwendungscode oder fehlerhafte Dependencies zur Laufzeit globale CLI-Binaries überschreiben oder manipulieren könnten.

Dockerfile

USER root

RUN mkdir -p /usr/local/share/npm-global \
  && chown -R node:node /usr/local/share/npm-global

ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
ENV PATH=$PATH:/usr/local/share/npm-global/bin

USER node

RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}

Diese Variante folgt dem Prinzip “Least Privilege auch zur Build-Zeit” und orientiert sich am offiziellen Claude Code Development Container sowie am Gemini CLI Container.

Dabei wird ein eigener globaler npm-Pfad eingerichtet, der dem node-User gehört. Die Installation erfolgt anschließend ohne Root-Rechte.

Vorteil:

Die Installation erfolgt ohne Root-Rechte

Nachteil:

Der node-User kann den globalen npm-Pfad zur Laufzeit verändern. Damit könnten globale CLI-Binaries durch nachgelagerten Code überschrieben oder manipuliert werden.

Beide Varianten sind technisch valide. Die Entwicklungsumgebung dieser Guideline orientiert sich am Vorgehen der offiziellen Container für Node-basierte CLIs:

• Sowohl das offizielle Claude Code Dockerfile als auch das Gemini CLI Dockerfile installieren die jeweilige CLI als node-User in einem eigenen npm-Prefix unter /usr/local/share/npm-global
• Damit ergibt sich ein für Node-basierte CLI-Container etablierter Standard, der Installationen ohne Root-Rechte ermöglicht und einen klar definierten Pfad für globale Tools bereitstellt

Claude Code nutzt bubblewrap als zusätzliche² Sandbox. Diese Sandbox sorgt dafür, dass ein ausgeführter Prozess nur auf bestimmte Dateien zugreifen darf und der Netzwerkzugriff eingeschränkt wird.

Für den Netzwerkzugriff verwendet Claude Code zusätzlich socat. Dabei wird der Netzwerkverkehr des Prozesses in der Sandbox über einen lokalen Proxy geleitet, der anhand der Sandbox-Settings entscheidet, welche Domains erlaubt oder blockiert sind.

Dockerfile

...
RUN apt-get update \
  && apt-get install -y --no-install-recommends \
    bubblewrap \
    socat \
...

Bubblewrap wurde primär für Szenarien entwickelt, in denen Prozesse direkt auf einem Linux-System isoliert werden müssen. In der Umgebung dieser Guideline läuft Claude Code jedoch bereits innerhalb eines gehärteten Docker-Containers mit cap_drop: ALL, no-new-privileges=true und dem Default-Seccomp-Filter von Docker.

Diese Hardening-Optionen verhindern, dass Bubblewrap die für seine OS-Level-Isolation benötigten User-Namespaces erstellen kann.

Selbst mit enableWeakerNestedSandbox aktiviert konnte die Sandbox im Setup dieser Guideline nicht zuverlässig in Betrieb genommen werden - neben den Capability- und Seccomp-Restriktionen kommen weitere Faktoren wie die Erwartung bestimmter Verzeichnisstrukturen (.git/hooks/) und bekannte Issues der aktuellen Claude Code Implementierung hinzu.

Eine Aktivierung wäre nur möglich, wenn man dem Container privilegierte Rechte gibt (etwa seccomp=unconfined und weitere Lockerungen). Das würde jedoch dem Hardening-Ansatz dieser Guideline widersprechen.

Eine vollständige Aktivierung von Bubblewrap würde zusätzliche privilegierte Rechte im Container erfordern. Damit würde die äußere Isolationsschicht geschwächt, um eine zusätzliche innere Schicht zu ermöglichen.

Auch wenn die Sandbox aktuell nicht aktiviert ist, bleiben bubblewrap und socat im AI Docker Image installiert.

Damit ist die Sandbox-Funktionalität im Image grundsätzlich verfügbar und kann mit einer zukünftigen Claude Code Version oder in einer weniger restriktiven Umgebung ohne Image-Änderung aktiviert werden.