DevOps & Deployment 2. Mai 2026 11 min Lesezeit

Claude Code + Docker: AI Agents containerisieren und deployen

Claude Code Agents in Docker-Container zu packen macht sie reproduzierbar, skalierbar und sicher deploybar. Hier ist die vollständige Strategie — von einem einzelnen Agent bis zu einem Multi-Agent-System mit Docker Compose.

Warum Docker für Claude Code Agents?

Ohne Container hängt dein Agent von der lokalen Umgebung ab: Node.js-Version, installierten Tools, Systemkonfiguration. Das funktioniert auf deinem Laptop — aber reproduzierbar auf einem VPS deployen? Schwierig.

Mit Docker ist der Agent immutable: gleiche Umgebung auf Laptop, Staging und Production. Außerdem hilft Container-Isolation bei Security: der Agent sieht nur was er sehen soll.

Basis-Dockerfile für einen Claude Code Agent

1Einfaches Single-Stage Dockerfile

# Dockerfile — Claude Code Agent (einfach)
FROM node:20-slim

# Security: nicht als root laufen
RUN useradd -m -s /bin/bash agent
WORKDIR /app
RUN chown agent:agent /app

# Claude Code CLI installieren
RUN npm install -g @anthropic-ai/claude-code

# Agent-Skripte und CLAUDE.md kopieren
COPY --chown=agent:agent . .

# Als non-root User laufen
USER agent

# API Key via Environment Variable (NIEMALS im Image)
ENV ANTHROPIC_API_KEY=""

CMD ["node", "agent.js"]

NIEMALS den ANTHROPIC_API_KEY in das Dockerfile hardcoden oder per COPY in das Image bringen. Immer via -e Flag oder Docker Secrets übergeben.

2Multi-Stage Build für Produktion

Multi-Stage Builds reduzieren die finale Image-Größe dramatically — nur was runtime nötig ist landet im finalen Image.

# Multi-Stage Dockerfile — Produktions-optimiert

# Stage 1: Dependencies installieren
FROM node:20-slim AS deps
WORKDIR /build
COPY package*.json ./
RUN npm ci --only=production

# Stage 2: Build (TypeScript kompilieren falls nötig)
FROM node:20-slim AS builder
WORKDIR /build
COPY --from=deps /build/node_modules ./node_modules
COPY . .
RUN npm run build 2>/dev/null || true  # TypeScript build, optional

# Stage 3: Finales minimales Image
FROM node:20-slim AS runtime
RUN useradd -m agent && npm install -g @anthropic-ai/claude-code
WORKDIR /app
COPY --from=builder --chown=agent:agent /build/dist ./dist
COPY --from=deps --chown=agent:agent /build/node_modules ./node_modules
COPY --chown=agent:agent CLAUDE.md .
USER agent
CMD ["node", "dist/agent.js"]

Docker Compose für Multi-Agent-Systeme

Wenn du mehrere Agents betreibst (CEO, Marketing, ICT...), koordiniert Docker Compose das Netzwerk zwischen ihnen.

DOCKER COMPOSE ARCHITEKTUR — Multi-Agent-System

strategy-agent (Port: intern) — CLAUDE.md: Strategy

marketing-agent (Port: intern) — CLAUDE.md: Marketing

n8n (Port: 5678) — Webhook-Automation

monitoring (Port: 3001) — Health-Checks

Alle Services im selben Docker Network → können sich via Service-Namen ansprechen

# docker-compose.yml — Multi-Agent-System
version: '3.9'

services:
  strategy-agent:
    build:
      context: .
      dockerfile: agents/strategy/Dockerfile
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - AGENT_ROLE=strategy
      - N8N_WEBHOOK_URL=http://n8n:5678/webhook
    volumes:
      - shared-memory:/app/shared-memory:rw
      - ./agents/strategy/CLAUDE.md:/app/CLAUDE.md:ro  # read-only!
    networks:
      - agent-network
    restart: unless-stopped

  marketing-agent:
    build:
      context: .
      dockerfile: agents/marketing/Dockerfile
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - AGENT_ROLE=marketing
    volumes:
      - shared-memory:/app/shared-memory:rw
      - ./agents/marketing/CLAUDE.md:/app/CLAUDE.md:ro
    networks:
      - agent-network
    restart: unless-stopped

  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=${N8N_USER}
      - N8N_BASIC_AUTH_PASSWORD=${N8N_PASSWORD}
    volumes:
      - n8n-data:/home/node/.n8n
    networks:
      - agent-network
    restart: unless-stopped

volumes:
  shared-memory:
  n8n-data:

networks:
  agent-network:
    driver: bridge

Wichtig: .env Datei für Secrets. Alle Secrets (API Keys, Passwörter) in einer .env Datei — niemals direkt in docker-compose.yml. Die .env kommt in .gitignore (aber bleibt deployt auf dem Server).

# .env (auf dem Server, NICHT im Git für öffentliche Repos)
ANTHROPIC_API_KEY=sk-ant-...
N8N_USER=admin
N8N_PASSWORD=sicheres-passwort-hier

Shared Memory zwischen Agents

Agents müssen Daten austauschen können. Docker Volumes sind die sauberste Lösung:

# In jedem Agent: shared-memory Volume wird gemountet
volumes:
  - shared-memory:/app/shared-memory:rw

# Strategy-Agent schreibt:
fs.writeFileSync('/app/shared-memory/strategy_status.md', statusUpdate);

# Marketing-Agent liest:
const status = fs.readFileSync('/app/shared-memory/strategy_status.md', 'utf8');

Deployment auf VPS

3Produktions-Deployment Workflow

# 1. Code auf Server kopieren
git clone git@github.com:dein-repo/agents.git /opt/agents
cd /opt/agents

# 2. .env erstellen (einmalig)
cp .env.example .env
nano .env  # API Keys eintragen

# 3. Images bauen und starten
docker compose up -d --build

# 4. Logs prüfen
docker compose logs -f strategy-agent

# 5. Update deployen (Zero-Downtime)
git pull
docker compose up -d --build --no-deps strategy-agent

Health Checks und Monitoring

# docker-compose.yml — Health Check für jeden Agent
strategy-agent:
  healthcheck:
    test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health')"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s

# Einfacher Health-Endpoint im Agent:
const http = require('http');
http.createServer((req, res) => {
  if (req.url === '/health') {
    res.writeHead(200);
    res.end(JSON.stringify({ status: 'ok', uptime: process.uptime() }));
  }
}).listen(3000);

Security Checkliste für Container

Non-root User: Agent läuft nicht als root im Container
Read-only Filesystem: read_only: true in docker-compose + explizite write Volumes
No-new-privileges: security_opt: ["no-new-privileges:true"]
Resource Limits: CPU und Memory Limits setzen (deploy.resources.limits)
Network Isolation: Agents nur im internen Netz, kein direkter Public Access
Secrets via .env: niemals Secrets im Image oder in Logs

Docker-Templates im Kurs

Im Claude Code Mastery Kurs findest du fertige Dockerfile + docker-compose.yml Templates für Single-Agent und Multi-Agent-Deployments — direkt für deinen VPS einsetzbar.

14 Tage kostenlos testen →