Selbst gehostete Dev-Sandboxes: Preview-Umgebungen mit Docker und Go bauen

Preview-URLs sehen wie ein winziges Feature aus: Port 3000 im Container starten, dem Nutzer einen Link geben, fertig. In der Praxis zieht eine selbst gehostete Dev-Sandbox schnell Port-Kollisionen, Domain-Routing, Container-Recycling, Dateipersistenz und API-gesteuerte Orchestrierung mit herein. KI-Coding-Produkte treffen das besonders früh: Nachdem der Agent Code geschrieben hat, will der Nutzer keine Logs. Er will auf das Ergebnis klicken.

Ein einzelnes docker run reicht hier nicht. Ein stabileres Design trennt vier Teile: einen Linux-Host, Docker für Container, eine Go-Control-Plane für den Lebenszyklus, Traefik für Preview-Domains und SQLite für den Status. Dieses Setup passt zu vertrauten Teams und früher Produktvalidierung. Wenn Sie beliebigen Code unbekannter Nutzer ausführen wollen, sind Container nur die erste Schicht. Dann sollten Sie an microVMs, dedizierte Hosts oder Kubernetes denken.

Für viele kurzlebige Umgebungen, nicht für zwei persönliche Container

Für ein persönliches Projekt reichen meist zwei Container, zwei Ports und docker compose up -d. Eine Dev-Sandbox lohnt sich, wenn die Zahl der Umgebungen wächst, der Lebenszyklus kürzer wird und ein externes System jede Umgebung programmatisch erstellen muss.

Viele Entwickler fragen zuerst, warum der Agent nicht einfach ein Shell-Skript schreibt. Berechtigte Frage. Ein Skript löst „einen Container starten”. Es löst nicht „50 Umgebungen am Leben halten, idle stoppen, beim nächsten Request aufwecken, Dateien behalten, jeder Umgebung eine stabile URL geben und alles über eine API von einem SaaS-Backend ansteuern”. Sobald sich diese Anforderungen stapeln, wächst aus dem Skript eine Control Plane.

Die kleinste Architektur: Go-Control-Plane, Docker, Traefik und SQLite

Das Design von tastyeffectco/sandboxes ist bewusst klein: Ein Go-Programm namens sandboxd schickt Docker-Befehle, Traefik routet dynamisch über Container-Labels, SQLite speichert den Status, und Workspaces liegen auf der Festplatte. Kein Kubernetes, kein separater Datenbankserver, keine Message Queue.

browser
  |
  v
Traefik  ---->  sandbox container  ----> dev server :3000
  ^                    ^
  |                    |
sandboxd --------------+
  |
  +-- SQLite: Sandbox-Status, Ports, Tasks
  +-- workspaces/: ein persistentes Verzeichnis pro Sandbox
  +-- reaper: idle stop / memory pressure stop

Es lohnt sich, vier Objekte zu trennen.

Die Control Plane ist nicht der Anwendungscontainer

Die Go-Control-Plane sollte nur den Lebenszyklus behandeln: Sandbox erstellen, stoppen, zerstören, einen Befehl ausführen, einen Agent-Task einreichen und Dateien lesen oder schreiben. Halten Sie sie dünn. Stecken Sie nicht die gesamte Build-Logik hinein. Komplexeres Verhalten kann im Sandbox-Basis-Image, in einer Task-Queue oder in der Anwendungsschicht darüber leben.

Eine Preview-URL ist kein zufälliger Port

Jede Sandbox kann eine Adresse wie s-<id>-3000.preview.localhost freigeben. Traefik liest Docker-Labels, ermittelt Zielcontainer und -port und leitet Requests über eine Host-Rule weiter. Nutzer sehen einen stabilen Link statt „dein Port ist 30017; kollidiere nicht mit jemandem”.

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

Jetzt starten →Anzeige

SQLite ist der Status-Anker für ein kleines System

Container starten neu. Hosts starten neu. Traefik kann neu laden. SQLite hält Sandbox-IDs, Ports, Status, Tasks und Workspace-Orte fest. Beim Start der Control Plane kann sie Dockers tatsächlichen Status mit dieser Datenbank reconcilen. SQLite ist für ein frühes Single-Host-Produkt in Ordnung, solange Sie die Grenze akzeptieren und sichern.

Lokal durchspielen: zuerst API, Ports und Domain-Auflösung validieren

Stürzen Sie sich nicht gleich auf das Anbinden eines Agenten. Bestätigen Sie zuerst, dass die Control Plane Container starten kann, Traefik weiterleiten kann und die Preview-URL sich öffnet. Der Quick Start aus der sandboxes-README ist direkt:

git clone https://github.com/tastyeffectco/sandboxes.git
cd sandboxes
./install.sh

API=http://127.0.0.1:9090
curl "$API/healthz"

Nachdem der Health-Check besteht, erstellen Sie eine Sandbox, die auf Port 3000 bereitstellt:

ID=$(curl -s -XPOST "$API/sandbox" \
  -H 'content-type: application/json' \
  -d '{"ports":[3000]}' | sed -E 's/.*"id":"([^"]+)".*/\1/')

curl -s -XPOST "$API/sandbox/$ID/exec" \
  -H 'content-type: application/json' \
  -d '{"cmd":["bash","-lc","cd ~/workspace && python3 -m http.server 3000"]}'

Dann öffnen Sie:

http://s-<id>-3000.preview.localhost

*.localhost löst in modernen Browsern auf den lokalen Rechner auf, praktisch für lokales Testen ohne DNS. Für eine echte Domain zeigen Sie *.preview.yourdomain.com auf den Host und lassen Traefik TLS übernehmen. Geben Sie eine lokale API wie 127.0.0.1:9090 nicht direkt ins öffentliche Internet. Aktivieren Sie in der Produktion mindestens Token-Authentifizierung und halten Sie den Control-Plane-Port hinter einer Firewall oder einem privaten Gateway.

Preview-URLs sind schwer wegen Routing, Wakeups und Persistenz

Einfaches Port-Forwarding beantwortet nur „wie greife ich auf den Container zu, während er läuft?” Eine Dev-Sandbox muss auch beantworten „was passiert, wenn der Container schläft?”, „wo liegen die Dateien?” und „kann derselbe Nutzer später zurückkommen?”. Diese drei Fragen entscheiden, ob das System von der Demo zum Beta kommt.

Routing: die Domain als Identität der Umgebung nutzen

Ein Port ist die Sicht der Maschine. Eine Domain ist die Sicht des Produkts. s-<id>-3000.preview.example.com enthält Sandbox-ID und Zielport, sodass die Anwendung den Link direkt anzeigen kann. Der Docker-Provider von Traefik liest Container-Labels und leitet die Host-Rule an den richtigen Container.

Suchen Sie bei Problemen in dieser Reihenfolge:

• DNS: zeigt die Wildcard-Domain auf den Host, oder nutzen Sie lokal *.localhost?
• Traefik: hat der Container die richtigen Labels und ist er im selben Docker-Netzwerk?
• Port: lauscht die App wirklich auf 0.0.0.0:3000 und nicht nur auf 127.0.0.1?
• Readiness: gibt es eine Warteseite oder Retry-Strategie, während die App startet?
• TLS: nutzt die echte Domain ein Wildcard-Zertifikat, und sind HTTP- und HTTPS-Entrypoints konsistent?

Wakeup: Idle-Stop ist kein Löschen der Umgebung

Eine idle Sandbox kann mit docker stop gestoppt werden, was Speicher freigibt und den Workspace auf der Festplatte behält. Wenn ein Nutzer das nächste Mal die Preview-URL öffnet, kann eine niedrigpriore Catch-all-Route den Request an die Control Plane geben. Die Control Plane startet den Container, wartet, bis der Port bereit ist, und lässt den Browser dann in die echte App.

Dieser Mechanismus nutzt weniger Ressourcen als „alles für immer an” und fühlt sich produktartiger an als „beim Ruhen löschen”. Der Preis ist Cold-Start-Latenz, daher sollte die Seite einen Warming-Status zeigen, statt den Nutzer auf einen 502 starren zu lassen.

Persistenz: Bind Mounts sind nützlich, aber kennen Sie die Grenze

Dockers Dokumentation behandelt Bind Mounts als üblich zum Teilen von Quellcode und Build-Artefakten. Eine Dev-Sandbox macht oft dasselbe: ein Host-Verzeichnis pro Sandbox, in den Workspace des Containers gemountet. Der Vorteil: Code überlebt das Löschen des Containers. Der Nachteil: Host-Pfade und Berechtigungen werden Teil des Systemdesigns.

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

15 % Rabatt sichern →Anzeige

Legen Sie vor einem Beta mindestens drei Regeln fest: Workspace-Verzeichnisse von der Control-Plane-Konfiguration trennen; „Container löschen” und „Workspace löschen” zu zwei verschiedenen Operationen machen; Workspaces und SQLite sichern, nicht nur Container-Layer.

Multi-Tenant-Grundlagen: Ressourcenlimits, Docker-Socket, API-Auth und Image-Caching

Dockers Dokumentation zu Ressourcenlimits ist deutlich: Container haben standardmäßig keine Ressourcen-Constraints und können CPU und Speicher so nutzen, wie der Host-Kernel-Scheduler es zulässt. In einem Multi-Tenant-Setup ist das ein Risiko. Das npm install, ein Build oder eine Endlosschleife eines Nutzers kann die ganze Maschine bremsen.

Beginnen Sie mit dieser Checkliste:

• Setzen Sie Speicher-, CPU- und PID-Limits für jede Sandbox.
• Halten Sie die Control-Plane-API standardmäßig auf localhost oder einem privaten Netzwerk; verlangen Sie Authentifizierung für jeden öffentlichen Entrypoint.
• Behandeln Sie Preview-Links standardmäßig als teilbar. Ergänzen Sie Forward-Auth, wenn sie sensible Inhalte enthalten.
• Installieren Sie gängige Tools im Basis-Image vor, damit nicht jede Sandbox alles erneut zieht.
• Docker Hub hat offizielle Rate-Limits und Fair-Use-Regeln. Melden Sie sich in der Produktion an, richten Sie Image-Caching ein oder nutzen Sie eine private Registry.
• Mounten Sie Sandbox-Workspaces separat und geben Sie /var/run/docker.sock niemals an Nutzercontainer.
• Protokollieren Sie Erstellung, Stoppen, Zerstören, Befehlsausführung und Agent-Tasks.

Ein Compose-Beispiel für Ressourcenlimits kann so aussehen:

services:
  sandbox-app:
    image: your-sandbox-base:latest
    deploy:
      resources:
        limits:
          cpus: "1.00"
          memory: 1G
          pids: 256

Das größere Sicherheitsthema ist der Docker-Socket. Wenn sandboxd den Host-Docker-Socket mountet, hat es hohe Autorität über den Host. Das kann akzeptabel sein, wenn Sie die Control Plane pflegen und Nutzer nur die erstellten Sandbox-Container betreten. Können Nutzer den Control-Plane-Container beeinflussen oder den Docker-Socket erlangen, springt das Risiko über die übliche Container-Grenze hinaus.

Wann zu microVMs, Kubernetes oder einer Managed-Plattform wechseln

Der Vorteil von Single-Host-Docker sind Kosten, Lesbarkeit und Änderungsgeschwindigkeit. Der Nachteil ist ebenso klar: Ein Host hat begrenzte Kapazität, die Sicherheitsgrenze hängt stark an Container-Isolation und Host-Governance, und das Scheduling ist schwächer als bei einem Cluster.

Dockers offizielles Sandboxes-Sicherheitsmodell ist ein nützlicher Referenzpunkt: Es setzt den KI-Agenten in eine microVM, gibt jeder Sandbox einen eigenen Docker-Daemon, ein eigenes Dateisystem und Netzwerk und hält den Host-Docker-Daemon von der Sandbox fern. Es kostet mehr Ressourcen, aber die Isolationsgrenze ist klarer.

Starten Sie also mit einem Single-Host-Setup, um die Produktschleife zu lernen: eine Umgebung erstellen, den Agenten Code schreiben lassen, die Preview öffnen, idle Sandboxes recyceln und Dateien behalten. Sobald echte Nutzer kommen, rüsten Sie die Isolationsschicht nach tatsächlichem Risiko auf. Nicht umgekehrt: Ziehen Sie das Team nicht wegen eines noch nicht existierenden Skalierungsproblems in die Cluster-Pflege.

Eine praktische Checkliste vom MVP bis zum Beta

Sie können in dieser Reihenfolge vorgehen, ohne alles auf einmal zu bauen:

1. Wählen Sie einen sauberen Linux-Host, der nur Sandbox-bezogene Dienste betreibt. Keine Datenbanken, CI-Runner oder Produktionsanwendungen daneben.
2. Konfigurieren Sie eine Wildcard-Preview-Domain wie *.preview.example.com. Validieren Sie zuerst lokal mit *.localhost.
3. Testen Sie die Control-Plane-API durch: create, exec, stop, destroy und healthz.
4. Installieren Sie Node.js, Python, Git, gängige Paketmanager und die unterstützten Agent-CLIs im Sandbox-Basis-Image vor.
5. Ergänzen Sie für jede Sandbox Ressourcenlimits, Idle-Recycling, Workspace-Persistenz und eine Zerstörungs-Policy.
6. Aktivieren Sie API-Authentifizierung und ergänzen Sie bei Bedarf Zugriffskontrolle für Preview-Links.
7. Protokollieren Sie Audit-Events. Überwachen Sie Host-Speicher, Festplatte, Container-Anzahl, Cold-Start-Zeit und 502-Rate.
8. Üben Sie Backup und Recovery für SQLite, Workspace-Verzeichnisse, .env und Basis-Image-Build-Skripte.

Wenn Ihr nächster Schritt das Anbinden von Code-Previews an CI ist, lesen Sie GitHub Actions Self-Hosted Runner: Der komplette Leitfaden für ein privates Deployment. Wollen Sie die generierte Next.js-App langfristig hosten, ist Weg von Vercel: Der komplette Leitfaden zum Self-Hosting von Next.js mit Docker näher an der zweiten Hälfte des Wegs. Für öffentliche Domains und Origin-Schutz geht es weiter mit Cloudflare-Origin-IP-Allowlisting.

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

Jetzt starten →Anzeige

FAQ

Worin unterscheidet sich eine Dev-Sandbox von Docker Compose?

Compose ist eher „ich deklariere eine Gruppe Dienste und starte sie”. Eine Dev-Sandbox ist eher „das Produkt-Backend erstellt, stoppt, weckt und zerstört Umgebungen auf Anfrage, und jede Umgebung bekommt eine URL”. Sind es wenige, langlebige Umgebungen, reicht Compose. Werden Umgebungen pro Nutzer, Branch oder Agent-Task dynamisch erstellt, brauchen Sie eine Control Plane.

Warum nicht Kubernetes?

Wenn Sie schon Cluster, Ingress, Image-Registry, Berechtigungen und Monitoring haben, ist Kubernetes eine starke Basis für standardisierte Umgebungen. Das Problem: Viele frühe Teams wollen nur einen KI-App-Builder oder eine interne Preview-Umgebung validieren, und die Cluster-Pflege kann schwerer werden als das Produkt selbst. Single-Host-Docker ersetzt Kubernetes nicht; es hält die erste Phase leicht.

Kann Container-Isolation Code unbekannter Nutzer ausführen?

Das würde ich nicht direkt tun. Container passen zu vertrauten Teams, internen Nutzern oder risikoarmen Demos. Beliebiger Code unbekannter Nutzer sollte in stärkerer Isolation laufen, etwa microVMs, dedizierten VMs, gVisor, Kata, Firecracker oder zumindest nach Mandant getrennten Hosts.

Braucht jede Preview-URL HTTPS?

Lokale *.localhost-Previews können mit HTTP starten. Für eine echte öffentliche Domain nutzen Sie HTTPS, besonders wenn Nutzer Token, Formulare oder Geschäftsdaten eingeben. Ein Wildcard-Zertifikat reduziert den Aufwand, für jede Sandbox ein eigenes Zertifikat auszustellen.

Gehen Dateien nach einem Idle-Stop verloren?

Solange der Workspace ein persistentes Verzeichnis ist, löscht docker stop keine Dateien. Heikel ist der Unterschied zwischen destroy und purge: das eine entfernt nur den Container, das andere auch den Workspace. Machen Sie diesen Unterschied in Produkt-UI und API-Namen klar.

Können Docker-Hub-Rate-Limits dieses System beeinflussen?

Ja. Wenn viele Umgebungen häufig starten, bauen und Images ziehen, kann die öffentliche Registry zu einer instabilen Abhängigkeit werden. Melden Sie sich in der Produktion bei Docker Hub an, richten Sie eine private Registry oder einen Image-Cache ein und backen Sie gängige Abhängigkeiten ins Basis-Image.

Fazit

Eine selbst gehostete Dev-Sandbox lohnt sich, aber sie ist nicht nur ein fortgeschrittenes docker run. Sie ist eine kleine Plattform: Die Control Plane besitzt den Lebenszyklus, der Reverse-Proxy die URLs, der State-Store die Wiederherstellung, und Ressourcenlimits plus Sicherheits-Policy verhindern, dass eine Umgebung den Host lahmlegt.

Der stabile Weg ist, die Produktschleife zuerst mit Single-Host-Docker zu bauen und dann nach realem Risiko aufzurüsten. Wenn es wenige Nutzer gibt, der Code vertrauenswürdig ist und das Team eine Single-Host-Grenze akzeptiert, reicht Go + Docker + Traefik + SQLite. Sobald unbekannte Nutzer, stärkere Isolation, Multi-Host-Scheduling oder Compliance-Governance ins Spiel kommen, gehören microVMs, Kubernetes oder eine Managed-Plattform auf den Tisch.

Weiterführende Quellen

• tastyeffectco/sandboxes
• Docker Resource constraints
• Docker Engine security
• Docker Hub usage and limits
• Docker Sandboxes security model
• Traefik Docker provider