BranchLift

Git für den Backend-Zustand deiner KI-Agenten.

Git-Worktrees isolieren Code. BranchLift isoliert und versioniert den PostgreSQL-, MySQL-, MongoDB-, Redis-, Kafka- und Docker-Compose-Zustand hinter jedem parallelen Coding-Agenten.

Jeder Agent erhält ein echtes Backend, das er mutieren kann, ohne mit einem anderen Agenten zu kollidieren. Dieser Zustand kann als unveränderlicher Child-Snapshot committet, diffed, zurückgesetzt oder auf eine Maschine verschoben werden, die du bereits kontrollierst.

main snapshot
├── agent/fix-auth      → isolated worktree + PostgreSQL + Redis + ports
├── agent/billing       → isolated worktree + PostgreSQL + Redis + ports
└── agent/migration     → isolated worktree + PostgreSQL + Redis + ports

BranchLift ist local-first, agenten-agnostisch, selbst gehostet und erfordert kein BranchLift-Konto, keinen gehosteten Dienst und keine kostenpflichtige Abhängigkeit.

Beweise die Isolation in fünf Minuten

Die integrierte Demo verwendet echte PostgreSQL-16- und Redis-7-Container. Diese Befehle erstellen zwei Umgebungen aus demselben Golden Snapshot, mutieren nur eine Datenbank, bewahren diese Mutation als Child-Snapshot, zeigen den Zustandsdiff und setzen die Umgebung zurück:

branchlift demo
cd branchlift-demo

# A second agent starts from the same immutable dev snapshot.
branchlift spawn agent/review --snapshot dev

# Mutate only agent/demo's PostgreSQL state.
branchlift exec agent/demo -- docker compose exec -T postgres \
  psql -U branchlift -d app -c "CREATE TABLE agent_demo (id integer PRIMARY KEY);"

# This prints an empty line: agent/review never sees agent/demo's table.
branchlift exec agent/review -- docker compose exec -T postgres \
  psql -U branchlift -d app -tAc "SELECT to_regclass('public.agent_demo');"

# Version the changed backend, inspect it, then restore golden state.
branchlift snapshot commit demo-mutated --from agent/demo
branchlift snapshot diff dev demo-mutated
branchlift reset agent/demo

Das ist der Kernvertrag: isolieren → mutieren → committen → diffen → zurücksetzen. Derselbe Lebenszyklus wird in öffentlicher Linux-CI gegen festgelegte Docmost-, n8n- und Langfuse-Stacks getestet; siehe den Evidenzvertrag.

Related MCP server: lazy-mcp-router

Lokale Kontrollebene

Die optionale Loopback-only-UI hält Umgebungen, unveränderliche Zustandslinien, Sicherheitslage, Remotes, Audit-Ereignisse und die begrenzte Agenten-Task-Überprüfung an einem Ort.

Wo BranchLift passt

Das Ökosystem der parallelen Agenten von 2026 hat hervorragende Session-Orchestratoren – Conductor, Vibe Kanban, Claude Squad, Nimbalyst – die Agenten auf Worktrees starten und Diffs visualisieren. Laufzeit-Orchestratoren wie Coasts gehen weiter mit isolierten Containern, geseedeten Volumes, Agenten-Shells, Secrets und Remote-Entwicklung. Cloud-Plattformen wie Codespaces, DevPod und E2B isolieren ganze Maschinen.

BranchLift geht am tiefsten auf die versionierte Backend-Zustandsschicht. Was auch immer deinen Worktree oder deine Agenten-Sitzung erstellt, BranchLift gibt ihm echten Compose-Zustand, der mutiert, als inhaltsadressierter Child-Snapshot committet, semantisch diffed und zurückgesetzt werden kann. Es bietet außerdem eine Docker-Sandbox mit minimalen Rechten und verwandelt Maschinen, die du bereits kontrollierst, über SSH mit strengen Host-Keys in Worker.

Verwende Coasts, wenn du einen breiteren All-in-One-Agenten-Arbeitsbereich und DinD-artige Laufzeit-Orchestrierung möchtest. Verwende BranchLift, wenn Datenbank-/Queue-/Cache-Mutationen reproduzierbar, überprüfbar, zurücksetzbar und über lokale und SSH-Hosts portabel sein müssen. Sie können auch kombiniert werden: BranchLift ist bewusst unter jeder Session-Schicht nützlich, die gewinnt.

Siehe docs/COMPARISON.md für die detaillierte Landschaftsübersicht vom August 2026.

Das Problem

Das Ausführen von Codex, Claude, Cursor oder einem anderen Coding-Agenten in separaten Worktrees isoliert nur Code. Zustandsbehaftete Backends kollidieren weiterhin:

• Migrationen verändern dieselbe Datenbank;

• Worker verbrauchen die Jobs eines anderen Agenten;

• Tests leeren eine gemeinsame Redis-Instanz;

• Compose-Stacks konkurrieren um feste Ports und Containernamen;

• jeder neue Stack startet leer und wiederholt langsame Migrationen und Seeds.

BranchLift bereitet einen gestoppten, unveränderlichen Golden Snapshot vor und klont seinen Zustand für jeden Branch. Auf APFS, Btrfs und reflink-fähigem XFS teilt der Klon anfänglich Speicherblöcke mit dem Snapshot, und nur geänderte Blöcke verbrauchen neuen Speicherplatz.

Aktueller Status

Der aktuelle Haupt-Branch deckt PostgreSQL 16, MySQL 8.4 LTS, MongoDB 8, Kafka 3.9 und Redis 7 durch echte Container-Lebenszyklus-Verträge ab. Der MongoDB-/Kafka-Vertrag verifiziert Seed, isolierte Mutation, Child-Snapshot-Commit, Reset und neu gestarteten Zustand; macOS hydratisiert WiredTiger automatisch in ein laufzeitnatives Volume, während Snapshots portabel bleiben. BranchLift importiert auch vorhandenen gestoppten konsistenten Compose-Zustand, räumt alte Laufzeiten sicher auf und führt öffentliche Linux-Lebenszyklus-Evidenz gegen festgelegte Docmost-, n8n- und Langfuse-Stacks aus.

Heute unterstützt:

• Docker Compose 2.24.4+ oder ein explizit ausgewählter Podman-Compose-Anbieter;

• Git-Worktrees;

• Erkennung und Isolation benannter Volumes;

• PostgreSQL auf macOS Docker Desktop und Linux;

• MySQL 8.4 LTS auf macOS Docker Desktop und Linux;

• MongoDB 8, Kafka 3.9, Redis 7 und generische benannte Volumes;

• macOS und Linux nativ, plus Windows über WSL2 mit Repositories im Linux-Dateisystem;

• APFS-clonefile und Linux-reflink, mit rekursivem Kopier-Fallback;

• ressourcenbegrenzte Docker-Sandbox-Ausführung mit allen Linux-Capabilities entfernt, no-new-privileges, read-only Root, kein Host-Docker-Socket und none, Backend-only oder ausgehender Netzwerkzugriff;

• Host-Agenten-Befehle nur nach explizitem Opt-in der Projektrichtlinie;

• begrenzte Env- und read-only /run/secrets/...-Datei-Injektion, ohne Secrets in einen Worktree zu schreiben;

• mehrere zusammengeführte Compose-Dateien, mit Legacy-compose.file-Kompatibilität;

• Auflistung unveränderlicher Snapshots und abhängigkeitsgeschütztes Löschen;

• Laufzeit-Audits und konservative Waisenbereinigung durch doctor --fix;

• prozessübergreifende Snapshot- und Instanz-Sperren mit Diagnose veralteter Besitzer;

• kontextbewusste Host-Befehle durch branchlift exec;

• Absturzwiederherstellung für verlassene Snapshot-Builds und Instanzerstellung;

• Anhängen an Worktrees, die bereits von Codex, Claude, einer IDE oder dem Benutzer erstellt wurden;

• idempotente Session-Start-Hooks für Codex, Claude Code und Cursor;

• einen lokalen MCP-Server, der Attach, Laufzeit-Gesundheit/Logs, Sicherheitslage, Snapshots/Diffs, Audit-Ereignisse und bereinigte Remote-Inventur bereitstellt;

• Live-Service-/Gesundheitsinspektion durch preview und gezielte Compose-Logs.

• Crash-konsistenten Snapshot-Import aus einem vorhandenen Compose-Projekt;

• altersgefilterte, sperrengeprüfte Garbage Collection für gestoppte und fehlgeschlagene Laufzeiten;

• festgelegte Kompatibilitätsverträge für Langfuse, n8n Hosting, Docmost, Twenty und Immich;

• öffentliche Linux-Lebenszyklus-Evidenz für Docmost, n8n Hosting und den sechs-Dienste-Langfuse-Stack;

• paralleles Multi-Volume-Klonen und Port-Erkennung;

• einen aufgezeichneten 512-MiB-Btrfs-reflink-Benchmark mit Rohproben.

• inhaltsadressierte Snapshot-Manifeste, Eltern-Linie, crash-konsistente Instanz-Commits und semantische Snapshot-Diffs;

• eine Loopback-only, token-geschützte Kontrollebenen-UI für Lebenszyklus, Zustand, Sicherheit, Audit und Remote-Operationen;

• SSH-Worker mit strengen Host-Keys, einem Whitelist-Protokoll und benutzerbezogener, sudo-freier Worker-Einrichtung.

• Remote-Entwicklung mit einem Befehl, mit konflikterkennender Live-Arbeitsbaum-Synchronisierung und automatischen Loopback-SSH-Port-Tunneln;

• sandbox-erzwungene Remote-Agenten-Shells ohne Host-Shell- oder Docker-Socket-Zugriff;

• persistente repository-scoped BuildKit-Builder mit Remote-Build und Cache-Verwaltung mit exakter Bestätigung.

• einen Fünf-Spalten-Agenten-Task-Arbeitsbereich mit privaten Prompts, Drag-and-Drop-Zustand, Prompt-Kopie und begrenzter read-only Git-Diff-Überprüfung;

• repository-scoped Viewer-/Operator-/Admin-UI-Tokens, deren Rohwerte nur einmal angezeigt und nie gespeichert werden;

• ein geheimnisfreies gemeinsames Dateisystem-Knotenregister für Teams, die keinen gehosteten Koordinationsdienst möchten;

• Docker-/Podman-CLI-Auswahl und explizite WSL2-Diagnose, ohne vorzutäuschen, dass native Windows-Besitzsemantik sicher ist.

Podman-Unterstützung deckt den lokalen Compose-, Volume-, Sandbox-, Preview- und Doctor-Lebenszyklus über BRANCHLIFT_CONTAINER_CLI=podman ab; Remote-persistentes BuildKit erfordert weiterhin bewusst Docker Buildx. Natives Windows wird nicht unterstützt – verwende WSL2.

Installation

Anforderungen: Node.js 22+, Git und Docker Compose 2.24.4+ oder Podman mit einem funktionierenden Compose-Anbieter.

npm install -g branchlift

# or
brew tap MuratKomurcu1/tap
brew trust --formula MuratKomurcu1/tap/branchlift
brew install branchlift

Homebrew 6 erfordert den expliziten Vertrauensschritt für jede nicht offizielle Tap-Formel. Das versionierte GitHub-Release-Tarball bleibt als npm-registrierungsunabhängiger Fallback verfügbar.

Siehe docs/INSTALL.md für Anforderungen, Quellinstallation und Paketverifizierung.

Schnellstart

Probiere das komplette Produkt in einem wegwerfbaren PostgreSQL- und Redis-Projekt aus:

branchlift demo

Oder initialisiere, genehmige, erstelle einen Snapshot und starte ein vorhandenes Compose-Repository mit einem Befehl:

branchlift quickstart agent/fix-auth --trust-policy

--trust-policy ist explizit, weil der Schnellstart überprüfte Compose-Gesundheitschecks und Seed-Befehle ausführen kann. Ohne es stoppt BranchLift nach der Konfigurationsanalyse und gibt den Richtlinien-Digest aus.

Führe dies in einem vorhandenen Git-Repository mit compose.yaml oder docker-compose.yml aus:

branchlift init --dry-run
branchlift init
branchlift inspect
branchlift security trust

init erstellt branchlift.yaml. Committe diese Datei und baue dann das Golden Backend einmal:

Es enthält automatisch die standardmäßige compose.override.yaml/docker-compose.override.yml-Begleitdatei und kopiert nur .env/.env.local-Dateien, die tatsächlich existieren. Verwende wiederholte --compose-Optionen für nicht standardmäßige Merge-Stacks.

branchlift snapshot dev

Wenn der normale Compose-Stack des Projekts bereits den gewünschten Zustand enthält, importiere ihn, anstatt ihn neu zu bauen und zu seeden:

branchlift snapshot import dev

# Supply the same project name used by `docker compose -p` when needed
branchlift snapshot import dev --project my-existing-stack

Import zeichnet die aktuell laufenden Dienste auf, stoppt nur diese Dienste für eine crash-konsistente Dateisystemkopie und stellt sie vor der Rückkehr wieder her. Der resultierende Snapshot ist unveränderlich; BranchLift klont niemals eine laufende Datenbank.

Erzeuge isolierte Branches und führe dann einen überprüften Befehl innerhalb der standardmäßigen Docker-Sicherheitsgrenze aus:

branchlift spawn agent/fix-auth
branchlift sandbox run agent/fix-auth --read-only-worktree -- npm test
branchlift list

Wenn ein Tool bereits einen Worktree erstellt und ausgecheckt hat, führe dies von diesem Worktree aus:

branchlift attach

Angehängte Worktrees werden als extern besessen aufgezeichnet. BranchLift verwaltet ihren Backend-Zustand, entfernt aber niemals den Worktree selbst.

Das Sandbox-Image muss bereits lokal vorhanden sein; BranchLift zieht und führt niemals implizit ein ungeprüftes Image aus. Baue ein Image mit Codex, Claude Code oder deinen anderen Tools, setze security.sandbox.image und führe den Agenten dann über branchlift sandbox run aus. Legacy-spawn -- AGENT-Host-Ausführung bleibt nur verfügbar, wenn security.allowHostAgentCommands explizit aktiviert ist.

Automatisches Anhängen beim Sitzungsstart und den projektspezifischen MCP-Server installieren, ohne vorhandene Agenteneinstellungen zu ersetzen:

branchlift agents install all
git add .codex .claude .cursor .mcp.json

Verwenden Sie codex, claude oder cursor anstelle von all, um nur einen Client zu konfigurieren. Codex fordert Sie auf, einen neuen Projekt-Hook vor dessen erstem Lauf zu überprüfen und als vertrauenswürdig einzustufen.

Prüfen Sie die exakten Ports und den Live-Status der Compose-Dienste und lesen Sie dann die Protokolle eines Dienstes:

branchlift preview
branchlift logs agent/fix-auth --service postgres --tail 100

Führen Sie Tests, Migrationen oder ein anderes Tool im Worktree und in der Umgebung einer vorhandenen Instanz aus:

branchlift exec agent/fix-auth -- npm test

Setzen Sie eine Umgebung auf den unveränderlichen Snapshot zurück:

branchlift reset agent/fix-auth

Bereinigen Sie den Laufzeitzustand, während der Git-Worktree und der Branch erhalten bleiben:

branchlift destroy agent/fix-auth

Zeigen Sie eine Vorschau auf alte gestoppte/fehlgeschlagene Umgebungen an oder entfernen Sie sie stapelweise:

branchlift gc --older-than 7d --dry-run
branchlift gc --older-than 7d

Die Garbage Collection wählt niemals laufende/gerade erstellte Instanzen aus, überprüft Kandidaten unter ihrer Lifecycle-Sperre erneut und entfernt nur BranchLift-eigene Worktrees. Externe Worktrees bleiben erhalten.

Entfernen Sie auch den Worktree, aber nur, wenn er sauber ist:

branchlift destroy agent/fix-auth --worktree

BranchLift löscht niemals den Git-Branch.

Konfiguration

branchlift init erzeugt eine minimale Datei:

version: 1
compose:
  files:
    - compose.yaml
  statefulServices:
    - postgres
    - redis
snapshot:
  default: dev
  healthTimeoutSeconds: 120
  seed: []
worktree:
  copyFiles:
    - .env

Snapshot-Seed-Befehle werden innerhalb eines bereits fehlerfreien Compose-Dienstes ausgeführt:

snapshot:
  default: dev
  healthTimeoutSeconds: 120
  seed:
    - service: api
      command: ["npm", "run", "db:migrate"]
    - service: api
      command: ["npm", "run", "db:seed"]

Der Snapshot-Stack wird sauber heruntergefahren, bevor sein Dateisystemzustand zum Klonen verfügbar gemacht wird.

Projekte, die normalerweise einen Override verwenden, können Dateien in der Compose-Zusammenführungsreihenfolge auflisten:

compose:
  files:
    - compose.yaml
    - compose.dev.yaml

Die ältere Form compose.file: compose.yaml bleibt lesbar.

Die Projektausführungsrichtlinie wird eingecheckt, während die maschinenlokale Freigabe und die Secret-Werte nicht eingecheckt werden:

security:
  sandbox:
    backend: docker
    image: my-reviewed-agent:local
    network: backend
    readOnlyRoot: true
    memory: 4g
    cpus: 2
    pidsLimit: 512
  allowHostAgentCommands: false
  allowSecretCommands: false
secrets:
  apiToken:
    source: { env: MY_API_TOKEN }
    target: { env: API_TOKEN }
    scopes: [sandbox]
    required: true
  credentials:
    source: { file: ~/.config/my-app/credentials.json }
    target: { file: /run/secrets/credentials.json }
    scopes: [sandbox]
    required: true
ui: { host: 127.0.0.1, port: 7788 }

Dateiziele sind auf /run/secrets/... und den Sandbox-Bereich beschränkt. Befehl-Secret-Quellen und Host-Agent-Befehle sind standardmäßig blockiert. Siehe docs/SECURITY-AND-SECRETS.md.

Überprüfen Sie branchlift.yaml und führen Sie dann branchlift security trust aus. BranchLift speichert außerhalb des Worktrees nur seinen Digest. Jede Konfigurationsänderung macht die Freigabe ungültig und blockiert Compose-Lifecycle-/Snapshot-Operationen, Sandbox-Ausführung, Secret-Auflösung und Host-Agent-Ausführung, bis der neue Digest überprüft und als vertrauenswürdig eingestuft wurde.

Übernehmen Sie eine nützliche mutierte Instanz als Child-Snapshot und vergleichen Sie sie, ohne eine Datenbank zu starten:

branchlift snapshot commit migrated --from agent/fix-auth
branchlift snapshot diff dev migrated

Öffnen Sie die lokale Control Plane oder registrieren Sie eine Maschine, die Sie per SSH steuern:

branchlift ui
branchlift remote add lab 192.0.2.10 --user developer --repo /srv/my-project
branchlift remote sync lab --snapshot dev
branchlift remote launch lab agent/fix-auth --snapshot dev
branchlift remote dev lab agent/fix-auth --snapshot dev

Der Bereich Workspace fügt ein fünfspaltiges Prompt-Kanban und eine schreibgeschützte Git-Überprüfung für registrierte Instanz-Worktrees hinzu. Der Teamzugriff erfolgt per Opt-in:

branchlift task add "Fix auth race" --prompt "Reproduce, fix, test, and summarize" --branch agent/fix-auth --agent codex
branchlift team token create reviewer --role viewer
branchlift ui --team-access

# Publish prompt-free node inventory to a shared NFS/SMB/SSHFS directory
branchlift team registry publish --directory /shared/branchlift-registry

Die UI bleibt auf Loopback beschränkt; Teammitglieder verbinden sich über einen authentifizierten SSH-Tunnel und verwenden ihr Repository-Token. Der Viewer kann inspizieren, der Operator kann Aufgaben erstellen/verschieben und Umgebungen bedienen, und der Admin kann zurücksetzen, zerstören, entfernen, bereinigen und widerrufen. Gemeinsame Registry-Einträge schließen absichtlich Prompts, Tokens, Secret-Werte und Worktree-Pfade aus. Siehe docs/TEAM.md.

remote sync installiert/überprüft den benutzerbezogenen Worker, überträgt den exakten committeten Git-HEAD und sendet nur Snapshot-Blobs, die das Remote-System nicht bereits besitzt. remote launch fügt einen Worktree mit exaktem Commit und ein isoliertes Backend hinzu. remote dev spiegelt dann getrackte sowie ungetrackte, nicht ignorierte Arbeitsdateien, öffnet Loopback-SSH-Weiterleitungen für entdeckte TCP-Dienste und gleicht kontinuierlich ab, bis es gestoppt wird. Die Live-Synchronisierung ist einseitig und lehnt Remote-Bearbeitungen ab, anstatt sie zu überschreiben. Es sind kein Cloud-Konto, kein Abonnement, kein öffentlicher Control-Daemon und kein Docker-in-Docker-Daemon erforderlich. Siehe docs/REMOTE.md.

Befehle

branchlift demo [--directory PATH] [--no-run] [--json]
branchlift quickstart [BRANCH] [--snapshot NAME] [--no-start] [--trust-policy]
branchlift platform [--json]
branchlift init [--compose FILE]... [--dry-run] [--json]
branchlift inspect [--json]
branchlift snapshot [create] [NAME]
branchlift snapshot import [NAME] [--project COMPOSE_PROJECT] [--json]
branchlift snapshot list [--json]
branchlift snapshot delete NAME
branchlift spawn BRANCH [--snapshot NAME] [--no-start] [-- AGENT ...]
branchlift attach [--snapshot NAME] [--no-start] [-- AGENT ...]
branchlift start BRANCH [-- AGENT ...]
branchlift stop BRANCH
branchlift exec BRANCH -- COMMAND ...
branchlift reset BRANCH [--no-start]
branchlift list [--json]
branchlift preview [BRANCH] [--json]
branchlift logs [BRANCH] [--service NAME] [--tail N] [--follow] [--timestamps]
branchlift destroy BRANCH [--worktree]
branchlift doctor [--fix] [--json]
branchlift gc [--older-than 7d] [--dry-run] [--json]
branchlift benchmark [SNAPSHOT] [--iterations N] [--json]
branchlift agents install [all|codex|claude|cursor] [--dry-run] [--json]
branchlift task list|add|move|remove
branchlift team token create|list|revoke
branchlift team registry publish|list --directory PATH
branchlift mcp
branchlift remote dev REMOTE BRANCH [--snapshot NAME] [--trust-policy] [--no-tunnel]
branchlift remote live-sync REMOTE BRANCH
branchlift remote watch REMOTE BRANCH [--interval MS]
branchlift remote tunnel start|status|stop|watch REMOTE BRANCH
branchlift remote shell REMOTE BRANCH [--network none|backend|outbound]
branchlift remote agent REMOTE BRANCH [--read-only-worktree] -- COMMAND ...
branchlift remote build REMOTE --tag IMAGE [--branch BRANCH] [--network default|none] [--cache-max 20gb]
branchlift remote cache inspect REMOTE
branchlift remote cache prune REMOTE --confirm prune

Wenn ein Agent gestartet wird, stellt BranchLift Folgendes bereit:

BRANCHLIFT_INSTANCE
BRANCHLIFT_CONTEXT
BRANCHLIFT_WORKTREE
COMPOSE_PROJECT_NAME
BRANCHLIFT_<SERVICE>_<CONTAINER_PORT>_HOST
BRANCHLIFT_<SERVICE>_<CONTAINER_PORT>_PORT
BRANCHLIFT_<SERVICE>_<CONTAINER_PORT>_URL

BRANCHLIFT_CONTEXT verweist auf JSON, das die zugewiesenen Host-Ports und Dienst-Endpunkte enthält. Beispielsweise erhält ein PostgreSQL-Dienst, der den Container-Port 5432 bereitstellt, BRANCHLIFT_POSTGRES_5432_PORT.

snapshot delete weigert sich, einen Snapshot zu entfernen, solange eine Instanz darauf verweist. doctor prüft Snapshot-Inhalte, Metadatenreferenzen, Worktrees, Compose-Dateien, Lifecycle-Sperren, Laufzeitstatus und Docker-Ressourcen. doctor --fix entfernt verifizierte veraltete Sperren, gleicht abgebrochene Operationen ab und entfernt verwaiste Ressourcen mit exakter BranchLift-Kennzeichnung. Wiederhergestellte Snapshot-Daten werden in den Diagnosezustand .failed-recovered-* umbenannt, anstatt gelöscht zu werden. Git-Branches, Worktrees und verwaltete Datenbankstatusverzeichnisse werden nicht stillschweigend verworfen.

Sicherheitsmodell

BranchLift untersucht Compose, bevor es den Laufzeitzustand verändert, und lehnt Konfigurationen ab, die nur scheinbar isoliert wären:

• feste container_name-Werte;

• network_mode: host;

• externe benannte Volumes;

• erkannte zustandsbehaftete Dienste ohne ein verwaltetes benanntes Volume.

Gemeinsame beschreibbare Bind-Mounts werden als Warnungen gemeldet, oder als Blocker, wenn sie zu einem zustandsbehafteten Dienst gehören. Zufällig vergebene Instanz-Ports werden immer auf Loopback veröffentlicht, anstatt auf alle Host-Schnittstellen ausgeweitet zu werden. .env wird mit Berechtigungen nur für den Eigentümer kopiert, wenn es im Worktree fehlt; Symlink-Quellen und Ausbrüche aus dem Zielverzeichnis werden abgelehnt.

Die Diagnose enthält für jeden Isolations-Blocker eine konkrete Empfehlung. Interpolierte oder absolute Bind-Quellen werden konservativ als gemeinsam genutzt behandelt. Generierte Overrides ersetzen verwaltete Mount-Ziele, ohne nicht zusammenhängende Bind-, Tmpfs-, Secret- oder Config-Mounts aus dem Quellprojekt zu löschen.

Verändernde Befehle erwerben eigentümergestempelte Dateisystemsperren. Ein widersprüchlicher Befehl schlägt fehl, anstatt mit Datenbankkopien oder dem Compose-Abbau um die Wette zu laufen. Agent- und exec-Kindprozesse laufen außerhalb der Lifecycle-Sperren, sodass langlaufende Tools die beabsichtigte Laufzeitsteuerung nicht verhindern.

Instanzen, die von spawn erstellt wurden, besitzen ihren generierten Worktree. Instanzen, die von attach erstellt wurden, markieren den aktuellen Worktree als extern. destroy --worktree lehnt externes Eigentum ab, bevor etwas gestoppt oder entfernt wird; einfaches destroy entfernt nur den BranchLift-Laufzeitzustand.

branchlift exec und explizit aktivierte Host-Agent-Befehle sind keine Sicherheitsgrenzen. branchlift sandbox run fügt eine gehärtete Docker-Grenze um den Befehl hinzu, aber sie ist keine VM-Grenze und gewährt absichtlich Zugriff auf den ausgewählten Worktree sowie auf jeden berechtigten Backend-/Secret-Zugriff. Compose-Anwendungsdienste behalten ihre eigenen Image- und Compose-Sicherheitseinstellungen. Siehe SECURITY.md und docs/SECURITY-AND-SECRETS.md.

Speicherverhalten

Der Laufzeitzustand befindet sich außerhalb des Repositorys:

~/.branchlift/
├── repos/<repo-id>/snapshots/<name>/volumes/
├── repos/<repo-id>/instances/<branch>/volumes[-<generation>]/
├── repos/<repo-id>/locks/
├── repos/<repo-id>/live-sync/
├── repos/<repo-id>/remote-tunnels/
├── repos/<repo-id>/events.jsonl
├── remotes.json
└── worktrees/<repo-id>/<branch>/

Überschreiben Sie das Wurzelverzeichnis mit BRANCHLIFT_HOME.

Reihenfolge der Kopierstrategie:

1. macOS-APFS-Clonefile (cp -c);

2. Linux-Reflink (cp --reflink=always);

3. sichere rekursive Kopie als Rückfalloption.

Der Volume-Baum jedes fertigen Snapshots wird nach dem Schreiben des Digest-Manifests host-seitig schreibgeschützt gemacht. Die Bereitstellung stellt den Schreibzugriff nur für den Eigentümer auf den geklonten Laufzeitzustand wieder her, niemals weltweiten Schreibzugriff. Jeder Reset klont in eine noch nie gemountete Volume-Generation und wechselt den generierten Compose-Override erst, nachdem der Klon validiert wurde. Die vorherige Generation wird entfernt, nachdem der Ersatz-Stack fehlerfrei ist. Dies vermeidet Docker-Desktop-Bind-Cache-Wettläufe und setzt niemals einen halb kopierten Reset als aktiven Pfad aus.

Messen Sie die Klon-Latenz im Vergleich zu einer erzwungenen Vollkopie-Baseline auf Ihrer Maschine:

branchlift benchmark dev --iterations 10

Für ein datenbankunabhängiges Fixture verwenden Sie npm run benchmark:synthetic -- --size-mib 256 --iterations 7. Für den festgelegten Docmost-Vergleich verwenden Sie npm run benchmark:docmost -- --dataset-mib 128 --iterations 3.

Das aufgezeichnete Docmost-Ergebnis wird bewusst nicht als Erfolg dargestellt: Der reale APFS-Zustands-Klon war 2,51× schneller als eine Vollkopie, aber der vollständige HTTP-bereite Pfad war 0,82×, weil Docker Desktop den bind-gemounteten PostgreSQL-Zustand langsamer startet. Beim öffentlichen Linux-Btrfs-Lauf betrug der Median des synthetischen 512-MiB-Klons 31,25 ms gegenüber 600,95 ms für die erzwungene Vollkopie, eine Beschleunigung um das 19,23-fache. Methodik, Rohdaten und Negativkontrollen finden Sie in docs/BENCHMARKS.md.

Entwicklung

npm install
npm run check
npm test

# Requires a running Docker daemon and pulls postgres:16-alpine, mysql:8.4, and redis:7-alpine
npm run test:e2e

# Fetches five pinned public Compose projects
npm run test:compat

# Typecheck, unit tests, audit, and package dry-run
npm run verify

Den genauen Support-Umfang und die öffentlichen Lifecycle-Nachweise finden Sie in docs/COMPATIBILITY.md, docs/EVIDENCE.md, docs/ARCHITECTURE.md, docs/SECURITY-AND-SECRETS.md, docs/REMOTE.md und CONTRIBUTING.md.

Die Architektur ist in docs/ARCHITECTURE.md dokumentiert.

Community

• Fehlerberichte und Funktionsvorschläge: GitHub Issues

• Fragen und Show-and-Tell: GitHub Discussions

• Beiträge: CONTRIBUTING.md — npm run verify muss vor jedem PR erfolgreich sein.

• Sicherheitsmeldungen: SECURITY.md — Bitte verwenden Sie private Security Advisories anstelle öffentlicher Issues.

Wenn BranchLift Ihnen einen Reseed-Zyklus erspart, markieren Sie das Repository mit einem Stern – es ist das wichtigste Entdeckungssignal für ein unabhängiges, nicht VC-finanziertes Projekt in dieser Kategorie.

Lizenz und Herkunft

Apache-2.0. BranchLift ist eine originäre Implementierung. Sie wird durch das öffentliche Verhalten und die Produktideen von Worktree-Umgebungswerkzeugen und Datenbank-Branching-Systemen angeregt, kopiert jedoch nicht deren Quellcode und beansprucht deren Arbeit nicht als eigene.