Self-Hosted Dev Sandboxes mit Docker und Go: Preview-URLs ohne Kubernetes

Für jeden PR eine eigene Preview-Umgebung zu öffnen, wird oft über Vercel oder Netlify gelöst. Wenn Kosten, private Netzwerke oder Infrastrukturkontrolle wichtiger sind, kann ein einzelner Docker-Host mit einer Go-Control-Plane diese Rolle übernehmen. Jede Sandbox bekommt eine eigene Preview-URL, Ressourcen haben Obergrenzen, und die Sicherheitsgrenze bleibt sichtbar. Kein Kubernetes, kein Multi-Node-Setup.

Entscheidungstabelle — wann welche Lösung passt

Bei „self-hosted preview environments“ denken viele zuerst an Shell-Skripte mit vielen docker run-Aufrufen oder springen direkt zu Kubernetes. Die bessere Reihenfolge ist eine Entscheidungstabelle.

Drei Kriterien entscheiden.

Teamgröße: Ein einzelner Host eignet sich am besten für bis zu etwa 10 parallele interne Previews. Als grobe Rechnung: 512 MB RAM plus 0,5 CPU pro Sandbox. Ein Host mit 16 GB RAM trägt ungefähr 20 Sandboxes, danach wird die Reserve dünn. Darüber brauchen Sie K8s-Scheduling oder zusätzliche Kapazität über microVMs.

Vertrauensgrenze: Interne Teammitglieder und vertrauenswürdige Nutzer können in Docker-Containern laufen. Wenn externe Fremde oder autonome Agents beliebigen Code ausführen, ist ein Docker-Socket-Design nicht sicher genug. Docker Sandboxes nutzen microVM-Isolation; jede Sandbox hat einen eigenen Docker Daemon, ein eigenes Dateisystem und ein eigenes Netzwerk.

Upgrade-Pfad: Starten Sie mit Single-Host-Docker, um Bedarf und Ressourcendichte zu validieren. Wenn Concurrency die Host-Grenze übersteigt oder Multi-Node-Verfügbarkeit nötig wird, wechseln Sie zu Kubernetes. Wenn die Vertrauensgrenze von „internes Team“ zu „externe Nutzer“ wechselt, wechseln Sie zu microVMs.

Das README von tastyeffectco/sandboxes positioniert die Lösung genau dort: AI App Builder, Agent Platforms und Coding Playgrounds auf einem einzelnen Docker-Host. Das ist keine microVM-Isolation, sondern eine Go-Control-Plane, die Container erstellt und Preview-URLs veröffentlicht.

Architektur zerlegt — die Kernkomponenten der Control Plane

Eine Single-Host-Docker-Preview ist nicht einfach eine Schleife über docker run. Sie braucht eine Control Plane für Lebenszyklus, Routing-Registrierung und Aufräumen. Die Architektur von tastyeffectco/sandboxes zerfällt in sechs Module.

Go-Control-Plane (sandboxd): Sie läuft in einem Container und mountet den Docker Socket des Hosts sowie ein Datenverzeichnis. Über die Docker CLI verwaltet sie Sandbox-Container: erstellen, starten, stoppen, löschen. Alle Sandbox-Metadaten liegen in SQLite als Source of Truth.

Docker-Socket-Mount: Das ist der Zugang der Control Plane zum Docker Daemon. Durch das Mounten von /var/run/docker.sock kann sandboxd Container erstellen und verwalten. Genau hier liegt die Privilegiengrenze: Mit dem Docker Socket hat die Control Plane sehr weitreichende Host-Rechte.

Traefik-Label-Registrierung: Beim Start eines Sandbox-Containers injiziert die Control Plane Traefik-Routing über Docker Labels. Traefik arbeitet als Reverse Proxy, liest die Labels und leitet Requests für *.preview.example.com zum passenden Container.

SQLite-Metadatenspeicher: Jede Sandbox hat eine eindeutige ID und ein Verzeichnis. Metadaten liegen in SQLite. Workspaces liegen unter SANDBOXED_DATA_DIR/workspaces/, je Sandbox ein Unterverzeichnis für Quellcode, Konfiguration und Artefakte.

Idle Reaper und Pressure Reaper: Der Idle Reaper stoppt inaktive Sandbox-Container nach einem Schwellenwert und gibt RAM frei. Der Pressure Reaper beobachtet Memory Pressure auf dem Host und stoppt ausgewählte Sandboxes, bevor der Host in OOM läuft. Diese beiden Reaper sind der Kern der Ressourcenrückgewinnung.

Wake Path: Wenn ein Sandbox-Container vom Idle Reaper gestoppt wurde, muss der erste Request auf die Preview-URL ihn wieder starten. Ein Traefik-Catch-all leitet den Request an die Control Plane. Diese startet den Container und liefert eine Warming Page, bis die App bereit ist.

Die kleinste brauchbare Version besteht aus Go-Control-Plane-Container, Docker-Socket-Mount, Traefik, SQLite und Idle Reaper. Für den lokalen Quick Start brauchen Sie Docker Engine und das Compose Plugin.

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

Preview-URL implementieren

Der Kern einer Preview-URL ist eine stabile Domain, kein Zufallsport. Jede Sandbox bekommt einen eigenen Hostnamen wie {sandbox_id}.preview.example.com.

Traefik Docker Provider konfigurieren

Traefik kann über den Docker Provider Routing-Konfiguration aus Container Labels lesen. Eine minimale Konfiguration sieht so aus:

# traefik.yml
providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false

exposedByDefault: false bedeutet: Nur Container mit expliziten Labels werden von Traefik entdeckt.

Host Rule und Docker Labels

Die Control Plane injiziert Labels beim Erstellen eines Sandbox-Containers. Beispiel:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.sandbox123.rule=Host(`sandbox123.preview.example.com`)"
  - "traefik.http.routers.sandbox123.entrypoints=websecure"
  - "traefik.http.services.sandbox123.loadbalancer.server.port=3000"

Die Host rule leitet Requests für sandbox123.preview.example.com an diesen Container. loadbalancer.server.port nennt den internen Port, auf dem die App im Container lauscht.

Wake-on-Request-Pfad

Nachdem der Idle Reaper einen Sandbox-Container gestoppt hat, löst der erste Request auf die Preview-URL den Wake Flow aus:

1. DNS löst auf Traefik auf; dafür braucht es Wildcard-DNS wie *.preview.example.com
2. Traefik kennt die Route der Sandbox, aber der Container ist gestoppt
3. Ein Traefik-Catch-all leitet den Request an den Wake Handler der Control Plane
4. Die Control Plane startet den Sandbox-Container und gibt eine Warming Page zurück
5. Sobald der Container bereit ist, leitet Traefik spätere Requests direkt an den Container

Der Catch-all braucht eine niedrigere Priorität als alle Sandbox-Router:

labels:
  - "traefik.http.routers.catch-all.rule=HostRegexp(`{subdomain:[a-z0-9-]+}.preview.example.com`)"
  - "traefik.http.routers.catch-all.priority=1"
  - "traefik.http.routers.catch-all.service=wake-service"

Alle Requests, die keine Live-Sandbox-Route treffen, landen im Catch-all. Die Control Plane übernimmt dann die Wake-Logik.

Sicherheitsgrenze — Rechte des Docker Socket

Den Docker Socket zu mounten, gibt der Control Plane Host-Root-ähnliche Macht. Das ist die Sicherheitsbasis dieser Architektur: geeignet für interne Teams und vertrauenswürdige Nutzer, nicht für untrusted Code Execution.

Risiken des Docker Socket

Die Docker-Dokumentation weist ausdrücklich auf die Angriffsfläche des Daemons hin. Wird die Docker API unsicher geöffnet, kann ein entfernter Nicht-Root-Nutzer Root-Zugriff auf den Host erlangen. Ein Container mit gemountetem /var/run/docker.sock kann über Docker CLI Container erstellen, ändern und löschen. Er kann über selbst erstellte Container auch auf Host-Dateisysteme und Netzwerke zugreifen.

Das bedeutet:

• Der Control-Plane-Container hat sehr hohe Rechte auf dem Host
• Control Plane und untrusted Workloads gehören nicht auf denselben Host
• Code in Sandbox-Containern kann den Host indirekt beeinflussen, wenn er die Control Plane beeinflussen kann

Grenze für nicht vertrauenswürdige Szenarien

Single-Host-Docker plus Go-Control-Plane passt für:

• Preview-Umgebungen interner Teammitglieder
• Coding Playgrounds für vertrauenswürdige Nutzer
• Interne Validierungsumgebungen für AI App Builder oder Agent Platforms

Nicht passend ist es für:

• Beliebige Codeausführung durch unbekannte externe Nutzer
• Produktionsausführung autonomer Agents, wenn der Host nicht vertraut ist
• Multi-Tenant-Plattformen mit starker Isolation

Wenn die Vertrauensgrenze von „internes Team“ zu „externe Nutzer“ wechselt, sollten Sie zu Docker Sandboxes oder Firecracker-microVMs wechseln. Docker Sandboxes kombinieren Hypervisor-Isolation, getrennte Netzwerke, eigenen Docker Daemon, eigenes Dateisystem und Credential-Isolation. Jede Sandbox ist eine vollständige microVM, kein Container, der den Host-Docker-Daemon teilt.

Production-Hardening-Checkliste

Für Produktion ergänzen Sie diese Grenzen:

• Netzwerkisolation: Control Plane und Sandbox-Container laufen in eigenen Netzwerken, nicht im Geschäftsnetz
• API-Authentifizierung: Lokale Quick Starts sind oft ohne Auth; Produktion braucht Token oder einen anderen Auth-Mechanismus
• Minimale Angriffsfläche: Preview-URLs gehen über Traefik, nicht über den Docker-API-Port
• TLS: Preview-URLs brauchen ein Wildcard-TLS-Zertifikat statt Klartext
• Logs und Monitoring: API-Requests der Control Plane und Container-Lifecycle-Events werden protokolliert und alarmiert

Für stärkere Grenzen vergleichen Sie gVisor, Firecracker und Kubernetes in einem AI-Agent-Sandbox-Design.

Ressourcenlimits — Memory / CPU / PIDs

Docker-Container haben standardmäßig keine Ressourcenlimits. Ohne Limits kann ein Sandbox-Container Host-RAM und CPU verbrauchen und andere Sandboxes sowie Host-Prozesse stören. Eine Multi-Tenant-Preview braucht harte Limits pro Container.

Standardverhalten von Docker

Die Docker-Dokumentation erklärt, dass Container Host-Ressourcen nutzen können, soweit der Kernel Scheduler es erlaubt. Ohne explizites --memory oder --cpus kann ein Container freie Host-Ressourcen beanspruchen.

Hartes Memory-Limit

--memory setzt die maximale Speichermenge für den Container. Beispiel:

docker run --memory="512m" --memory-swap="512m" sandbox-image

--memory-swap setzt das Limit für Memory plus Swap. Wenn --memory-swap gleich --memory ist, nutzt der Container keinen Swap.

Überschreitet der Container das Memory-Limit, kann der OOM Killer Container-Prozesse beenden. Ein Host-OOM kann auch andere Container und Host-Prozesse treffen.

CPU-Anteil begrenzen

--cpus begrenzt, wie viel CPU-Kapazität ein Container nutzen darf. Beispiel:

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

docker run --cpus="0.5" sandbox-image

Der Container kann höchstens die Rechenleistung von 0,5 CPU nutzen. Bei vielen parallelen Sandboxes verhindert das, dass ein Container alle CPU-Ressourcen belegt.

Prozessanzahl begrenzen

--pids-limit schützt vor Fork Bombs. Beispiel:

docker run --pids-limit=100 sandbox-image

Der Container kann höchstens 100 Prozesse erstellen. Danach schlägt fork() fehl.

Compose-Konfigurationsbeispiel

Mit Docker Compose konfigurieren Sie Limits unter deploy.resources.limits:

services:
  sandbox:
    image: sandbox-image
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
          pids: 100

deploy.resources in Compose greift im Docker-Swarm-Modus. Auf einem einzelnen Docker-Host übergeben Sie --memory, --cpus und --pids-limit manuell oder nutzen docker-compose --compatibility.

Die Control Plane sollte diese Parameter beim Erstellen der Sandbox-Container setzen, statt Nutzer auf manuelle Konfiguration zu verweisen.

Betrieb — Image Cache und Docker-Hub-Rate-Limits

Wenn viele Sandboxes häufig erstellt und zerstört werden, werden Image Pulls zum Engpass. Docker Hub hat Pull Rate Limits und Abuse Rate Limits; Details hängen von Account-Typ und Plan ab. Produktion sollte nicht jeden Sandbox-Start direkt vom öffentlichen Docker Hub abhängig machen.

Docker-Hub-Limits

Die Docker-Dokumentation beschreibt unterschiedliche Pull-Limits für anonyme Nutzer, authentifizierte Nutzer und Team-Accounts. Nach Überschreiten des Limits werden Pull Requests abgelehnt. Konkrete Zahlen können sich ändern; prüfen Sie die Docker-Hub-Seite statt Werte in den Text zu schreiben.

In Multi-Sandbox-Szenarien bedeutet das:

• Häufige Sandbox-Erstellung kann bei jedem Container-Start Images ziehen
• Nach einem Idle-Reaper-Stopp kann ein Neustart erneut ein Image benötigen
• Mehrere Sandboxes ziehen dasselbe Image wiederholt

Image Pre-Warming und Cache-Strategie

Produktion braucht einige Gegenmaßnahmen.

Image Pre-Warming: Ziehen Sie häufig genutzte Images vor dem Start der Control Plane auf den Host. Das reduziert Wartezeit beim Sandbox-Start.

Private Registry: Legen Sie häufig genutzte Images in einer privaten Registry ab, etwa Harbor, AWS ECR oder Google Artifact Registry. Die Control Plane zieht dann von dort statt direkt von Docker Hub.

Docker-Hub-Login: Wenn Sie Docker Hub nutzen müssen, verwenden Sie einen authentifizierten Account für das passende Pull-Kontingent. Docker empfiehlt für Produktion Login statt anonymer Pulls.

Image Cache: Der Docker Daemon cached bereits gezogene Layer. Wenn Sandbox-Container oft gelöscht und neu erstellt werden, darf Cleanup nützliche Layer nicht zu aggressiv entfernen.

Interne Registry-Beschleunigung

Wenn der Host in einem privaten Netzwerk liegt, konfigurieren Sie Registry Mirrors oder Proxys gegen Docker-Pull-Timeouts. Behandeln Sie das als Plattformbestandteil, nicht als Nacharbeit nach dem ersten Ausfall.

Troubleshooting-Checkliste — Preview-URL ist nicht erreichbar

Wenn die Preview-URL nicht öffnet, prüfen Sie diese fünf Punkte in Reihenfolge.

1. Zeigt DNS auf Traefik?

Prüfen Sie den Wildcard-DNS-Record. Der A-Record oder CNAME für *.preview.example.com sollte auf die IP des Traefik-Hosts zeigen.

Nutzen Sie dig oder nslookup:

dig sandbox123.preview.example.com

Die zurückgegebene IP sollte die Traefik-Host-IP sein, nicht eine andere Adresse.

2. Hat Traefik die Container Labels entdeckt?

Prüfen Sie die Traefik-Docker-Provider-Konfiguration und die Container Labels.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Nutzen Sie Traefik Dashboard oder Logs:

docker logs traefik-container | grep "sandbox123"

Die Traefik-Logs sollten zeigen, dass die Route für sandbox123 entdeckt wurde. Falls nicht, prüfen Sie:

• Ob das Label traefik.enable=true vorhanden ist
• Ob exposedByDefault: false korrekt gesetzt ist
• Ob Traefik den Docker Socket korrekt mountet

3. Läuft der Container?

Prüfen Sie den Zustand des Sandbox-Containers.

Nutzen Sie docker ps:

docker ps | grep sandbox123

Ist der Container gestoppt, hat ihn vielleicht der Idle Reaper gestoppt oder der Wake Path konnte ihn nicht neu starten. Ein Aufruf der Preview-URL sollte den Wake Handler der Control Plane auslösen, der den Container startet und eine Warming Page zurückgibt. Wenn das fehlschlägt, prüfen Sie die Control-Plane-Logs.

4. Auf welcher Adresse lauscht die App?

Prüfen Sie Adresse und Port innerhalb des Containers.

Öffnen Sie den Container und prüfen Sie die Listening Ports:

docker exec sandbox123 netstat -tuln

Die App sollte auf 0.0.0.0:3000 lauschen, nicht nur auf 127.0.0.1:3000. Die Docker-Dokumentation weist darauf hin, dass Ports, die an 127.0.0.1 oder ::1 gebunden sind, nur vom Docker-Host erreichbar sind. Externe Requests kommen dann nicht an.

Wenn die App nur auf localhost lauscht, ändern Sie die App-Konfiguration oder nutzen Sie einen passenden Netzwerkmodus.

5. Passt das Port Binding?

Vergleichen Sie den Traefik-Service-Port mit dem Port, auf dem die App tatsächlich lauscht.

Das Traefik Label kann so aussehen:

- "traefik.http.services.sandbox123.loadbalancer.server.port=3000"

Die App im Container sollte auf Port 3000 lauschen. Zeigt Traefik auf 3000, aber die App auf 8080, schlägt der Request fehl.

Wenn die Ports nicht passen, korrigieren Sie die Traefik Labels oder die App-Konfiguration.

Fazit

Single-Host-Docker plus Go-Control-Plane kann eine selbst gehostete Preview-Umgebung tragen: Jede Sandbox hat eine eigene Preview-URL, Ressourcen sind begrenzt, und die Sicherheitsgrenze ist klar. Der passende Bereich bleibt eng: interne Teams, vertrauenswürdige Nutzer, kleine Parallelität. Sobald die Vertrauensgrenze externe Fremde umfasst oder die Parallelität einen Host sprengt, wechseln Sie zu microVMs oder Kubernetes.

Die Kernmodule sind überschaubar: Die Entscheidungstabelle hält den Scope ehrlich. Die Architekturzerlegung zeigt Control Plane, Traefik, SQLite und Reaper. Preview-URLs hängen an Traefik Host Rules und Docker Labels. Die Sicherheitssektion behandelt den Docker Socket als Host-Root-ähnliche Macht. Ressourcenlimits sind die Basis für Multi-Tenant-Betrieb. Image Caching reduziert Docker-Hub-Risiken. Die Troubleshooting-Checkliste hilft, wenn Preview-URLs brechen.

Nächste Schritte:

• Kleine interne Team-Previews: mit Single-Host-Docker plus Go-Control-Plane starten und Ressourcendichte messen
• Externe Nutzer oder riskante Workloads: Docker Sandboxes, Firecracker oder eine andere microVM-Grenze nutzen
• Self-hosted CI Runner: den GitHub-Actions-Self-hosted-Runner-Leitfaden lesen und die private Infrastruktur ergänzen
• Apps in der Preview-Umgebung: den Next.js-Docker-Self-hosting-Leitfaden nutzen, um die App in der Sandbox auszuführen