BranchLift

为你的 AI 代理后端状态提供 Git 支持。

Git worktrees 隔离代码。BranchLift 隔离并对版本化每个并行编码代理背后的 PostgreSQL、MySQL、MongoDB、Redis、Kafka 和 Docker Compose 状态。

每个代理都能获得一个真实的后端，可以随意修改而不会与其他代理冲突。该状态可以提交为不可变的子快照，进行 diff、重置，或移动到你已经控制的机器上。

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 是本地优先、代理无关、自托管的，并且不需要 BranchLift 账户、托管服务或付费依赖。

五分钟内证明隔离性

内置演示使用真实的 PostgreSQL 16 和 Redis 7 容器。以下命令从同一个黄金快照创建两个环境，仅修改一个数据库，将该修改保留为子快照，显示状态差异，并重置环境：

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

这是核心契约：隔离 → 修改 → 提交 → 差异 → 重置。同样的生命周期在公共 Linux CI 中针对固定的 Docmost、n8n 和 Langfuse 技术栈进行了验证；请参阅证据契约。

Related MCP server: local-mcp-toolbox

本地控制平面

可选的仅回环 UI 将环境、不可变状态谱系、安全态势、远程、审计事件和有界代理任务审查集中在一个地方。

BranchLift 的定位

2026 年并行代理生态系统拥有出色的会话编排器——Conductor、Vibe Kanban、Claude Squad、Nimbalyst——它们在 worktrees 上启动代理并可视化差异。运行时编排器如 Coasts 更进一步，提供隔离容器、种子卷、代理 shell、机密和远程开发。云平台如 Codespaces、DevPod 和 E2B 隔离整个机器。

BranchLift 在版本化后端状态层上做得最深。无论谁创建你的 worktree 或代理会话，BranchLift 都为其提供真实的 Compose 状态，可以修改、提交为内容寻址的子快照、语义化 diff 和重置。它还提供最小权限的 Docker 沙箱，并将你已经控制的机器通过严格主机密钥 SSH 转变为工作节点。

当你想要更广泛的一体化代理工作区和 DinD 风格运行时编排时，使用 Coasts。当数据库/队列/缓存修改必须可重现、可审查、可重置，并且可在本地和 SSH 主机之间移植时，使用 BranchLift。它们也可以组合：BranchLift 刻意设计为在任何胜出的会话层之下都有用。

参见 docs/COMPARISON.md 了解 2026 年 8 月的详细环境评估。

问题

在单独的 worktrees 中运行 Codex、Claude、Cursor 或其他编码代理只能隔离代码。有状态后端仍然会冲突：

• 迁移修改同一个数据库；

• 工作进程消费另一个代理的任务；

• 测试清空共享的 Redis 实例；

• Compose 技术栈竞争固定端口和容器名称；

• 每个新技术栈都从空开始，重复缓慢的迁移和种子。

BranchLift 准备一个停止的、不可变的黄金快照，并为每个分支克隆其状态。在 APFS、Btrfs 和支持 reflink 的 XFS 上，克隆最初与快照共享磁盘块，只有更改的块才消耗新空间。

当前状态

当前 main 分支通过真实的容器生命周期契约覆盖 PostgreSQL 16、MySQL 8.4 LTS、MongoDB 8、Kafka 3.9 和 Redis 7。MongoDB/Kafka 契约验证种子、隔离修改、子快照提交、重置和重新生成的状态；macOS 自动将 WiredTiger 水合到运行时原生卷中，同时保持快照可移植。BranchLift 还导入现有的停止一致 Compose 状态，安全地垃圾回收旧运行时，并针对固定的 Docmost、n8n 和 Langfuse 技术栈运行公共 Linux 生命周期证据。

目前支持：

• Docker Compose 2.24.4+ 或明确选择的 Podman Compose 提供商；

• Git worktrees；

• 命名卷发现和隔离；

• macOS Docker Desktop 和 Linux 上的 PostgreSQL；

• macOS Docker Desktop 和 Linux 上的 MySQL 8.4 LTS；

• MongoDB 8、Kafka 3.9、Redis 7 和通用命名卷；

• 原生 macOS 和 Linux，以及通过 WSL2 的 Windows，仓库保留在 Linux 文件系统中；

• APFS clonefile 和 Linux reflink，带递归复制回退；

• 资源受限的 Docker 沙箱执行，丢弃所有 Linux 能力，no-new-privileges，只读根，无主机 Docker socket，以及 none、仅后端或出站网络；

• 仅在明确的项目策略选择加入后才允许主机代理命令；

• 作用域环境变量和只读 /run/secrets/... 文件注入，不将机密写入 worktree；

• 多个合并的 Compose 文件，兼容旧版 compose.file；

• 不可变快照列表和依赖保护的删除；

• 通过 doctor --fix 进行运行时审计和保守的孤儿清理；

• 跨进程快照和实例锁，带陈旧所有者诊断；

• 通过 branchlift exec 进行上下文感知的主机命令；

• 对放弃的快照构建和实例创建进行崩溃恢复；

• 附加到 Codex、Claude、IDE 或用户已创建的 worktrees；

• 为 Codex、Claude Code 和 Cursor 提供幂等的会话启动钩子；

• 本地 MCP 服务器，暴露附加、运行时健康/日志、安全态势、快照/差异、审计事件和清理后的远程清单；

• 通过 preview 和定向 Compose 日志进行实时服务/健康检查。

• 从现有 Compose 项目导入崩溃一致快照；

• 对停止和失败的运行时进行年龄过滤、锁重新检查的垃圾回收；

• 针对 Langfuse、n8n Hosting、Docmost、Twenty 和 Immich 的固定兼容性契约；

• 针对 Docmost、n8n Hosting 和六服务 Langfuse 技术栈的公共 Linux 生命周期证据；

• 并行多卷克隆和端口发现；

• 记录的 512 MiB Btrfs reflink 基准测试，带原始样本。

• 内容寻址的快照清单、父谱系、崩溃一致的实例提交和语义快照差异；

• 仅回环、令牌保护的控制平面 UI，用于生命周期、状态、安全、审计和远程操作；

• 严格主机密钥 SSH 工作节点，带允许列表协议和用户作用域、无 sudo 的工作节点设置。

• 一键远程开发，带冲突检测的实时工作树同步和自动回环 SSH 端口隧道；

• 沙箱强制的远程代理 shell，无主机 shell 或 Docker socket 访问；

• 持久仓库范围的 BuildKit 构建器，带远程构建和精确确认缓存管理。

• 五列代理任务工作区，带私有提示、拖放状态、提示复制和有界只读 Git diff 审查；

• 仓库范围的查看器/操作员/管理员 UI 令牌，原始值仅显示一次且永不持久化；

• 无秘密的共享文件系统节点注册表，适用于不希望托管协调服务的团队；

• Docker/Podman CLI 选择和明确的 WSL2 诊断，不假装原生 Windows 所有权语义是安全的。

Podman 支持通过 BRANCHLIFT_CONTAINER_CLI=podman 覆盖本地 Compose、卷、沙箱、预览和 doctor 生命周期；远程持久 BuildKit 仍然刻意要求 Docker Buildx。不支持原生 Windows——请使用 WSL2。

安装

要求：Node.js 22+、Git 和 Docker Compose 2.24.4+ 或带可用 Compose 提供商的 Podman。

npm install -g branchlift

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

Homebrew 6 要求对每个非官方 tap 公式进行显式信任步骤。 版本化的 GitHub Release tarball 仍然作为独立于 npm 注册表的回退可用。

参见 docs/INSTALL.md 了解要求、源码安装和包验证。

快速开始

在一个一次性的 PostgreSQL + Redis 项目中试用完整产品：

branchlift demo

或者使用一条命令初始化、批准、快照并启动现有的 Compose 仓库：

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

--trust-policy 是显式的，因为快速启动可能执行经过审查的 Compose 健康检查和种子命令。没有它，BranchLift 会在配置分析后停止，并打印策略摘要。

在包含 compose.yaml 或 docker-compose.yml 的现有 Git 仓库中运行：

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

init 创建 branchlift.yaml。提交该文件，然后构建一次黄金后端：

它自动包含标准的 compose.override.yaml/docker-compose.override.yml 伴生文件，并仅复制实际存在的 .env/.env.local 文件。对于非标准合并技术栈，使用重复的 --compose 选项。

branchlift snapshot dev

如果项目的正常 Compose 技术栈已经包含你想要的状态，则导入它而不是重建和重新播种：

branchlift snapshot import dev

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

导入记录当前运行的服务，仅停止这些服务以进行崩溃一致的文件系统复制，并在返回前恢复它们。生成的快照是不可变的；BranchLift 从不克隆运行中的数据库。

生成隔离分支，然后在默认 Docker 安全边界内运行审查过的命令：

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

如果工具已经创建并检出了 worktree，则从该 worktree 运行：

branchlift attach

附加的 worktrees 被记录为外部拥有。BranchLift 管理它们的后端状态，但从不删除 worktree 本身。

沙箱镜像必须已经存在于本地；BranchLift 从不隐式拉取和执行未审查的镜像。构建包含 Codex、Claude Code 或其他工具的镜像，设置 security.sandbox.image，然后通过 branchlift sandbox run 运行代理。仅当显式启用 security.allowHostAgentCommands 时，旧版 spawn -- AGENT 主机执行才可用。

安装自动会话启动附加组件和项目范围的 MCP 服务器，而不替换现有的代理设置：

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

使用 codex、claude 或 cursor 而不是 all 来仅配置一个客户端。Codex 会要求你在首次运行前审查并信任一个新的项目钩子。

检查确切的端口和实时 Compose 服务健康状态，然后读取一个服务的日志：

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

在现有实例的工作树和环境中运行测试、迁移或其他工具：

branchlift exec agent/fix-auth -- npm test

将环境重置为不可变快照：

branchlift reset agent/fix-auth

清理运行时状态，同时保留 Git 工作树和分支：

branchlift destroy agent/fix-auth

批量预览或移除旧的已停止/失败的环境：

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

垃圾回收从不选择正在运行/创建中的实例，会在其生命周期锁下重新检查候选者，并且只移除 BranchLift 拥有的工作树。外部工作树会被保留。

也移除工作树，但仅当它是干净的：

branchlift destroy agent/fix-auth --worktree

BranchLift 从不删除 Git 分支。

配置

branchlift init 生成一个最小文件：

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

快照种子命令在已经健康的 Compose 服务内执行：

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

快照堆栈在使其文件系统状态可用于克隆之前会被干净地关闭。

通常使用覆盖文件的项目可以按 Compose 合并顺序列出文件：

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

旧的 compose.file: compose.yaml 形式仍然可读。

项目执行策略被提交，而其机器本地的批准和密钥值则不会：

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 }

文件目标被限制在 /run/secrets/... 和沙箱范围内。命令密钥源和主机代理命令默认被阻止。参见 docs/SECURITY-AND-SECRETS.md。

在审查 branchlift.yaml 之后，运行 branchlift security trust。BranchLift 只在其工作树之外存储其摘要。任何配置更改都会使批准失效，并阻止 Compose 生命周期/快照操作、沙箱执行、密钥解析和主机代理执行，直到新的摘要被审查并信任。

将一个有用的变异实例提交为子快照，并在不启动数据库的情况下进行比较：

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

打开本地控制平面或通过 SSH 注册你控制的机器：

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

Workspace 部分为已注册的实例工作树添加了一个五泳道提示看板和只读 Git 审查。团队访问是选择加入的：

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

UI 仍然仅限回环；队友通过经过身份验证的 SSH 隧道连接并使用他们的仓库令牌。查看者可以检查，操作者可以创建/移动任务并操作环境，管理员可以重置、销毁、移除、清理和撤销。共享注册表记录有意排除提示、令牌、密钥值和工作树路径。参见 docs/TEAM.md。

remote sync 自动安装/验证用户范围的 worker，传输确切的已提交 Git HEAD，并且只发送远程尚未拥有的快照 blob。remote launch 添加一个精确提交的工作树和隔离的后端。remote dev 然后镜像已跟踪和未跟踪但未忽略的工作文件，为发现的 TCP 服务打开回环 SSH 转发，并持续协调直到停止。实时同步是单向的，拒绝远程编辑而不是覆盖它们。不需要云账户、订阅、公共控制守护进程或 Docker-in-Docker 守护进程。参见 docs/REMOTE.md。

命令

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

当代理启动时，BranchLift 提供：

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 指向包含分配的主机端口和服务端点的 JSON。例如，暴露容器端口 5432 的 PostgreSQL 服务会收到 BRANCHLIFT_POSTGRES_5432_PORT。

snapshot delete 拒绝在有任何实例引用快照时移除它。doctor 检查快照内容、元数据引用、工作树、Compose 文件、生命周期锁、运行时状态和 Docker 资源。doctor --fix 移除已验证的过期锁，协调被放弃的操作，并移除带有 BranchLift 标签的精确孤儿资源。恢复的快照数据被重命名为 .failed-recovered-* 诊断状态而不是删除。Git 分支、工作树和受管理的数据库状态目录不会被静默丢弃。

安全模型

BranchLift 在修改运行时状态之前检查 Compose，并拒绝那些看起来是隔离的配置：

• 固定的 container_name 值；

• network_mode: host；

• 外部命名卷；

• 检测到的有状态服务没有受管理的命名卷。

共享的可写绑定挂载被报告为警告，或者当它们属于有状态服务时被报告为阻止项。随机化的实例端口总是在回环上发布，而不是扩展到每个主机接口。当 .env 不在工作树中时，它以仅所有者权限复制；符号链接源和目标父目录逃逸被拒绝。

诊断包括针对每个隔离阻止项的具体建议。插值或绝对绑定源被保守地视为共享。生成的覆盖文件替换受管理的挂载目标，而不会删除源项目中无关的绑定、tmpfs、密钥或配置挂载。

修改命令获取所有者标记的文件系统锁。冲突的命令会失败，而不是竞争数据库副本或 Compose 拆除。代理和 exec 子进程在生命周期锁之外运行，因此长时间运行的工具不会阻止有意的运行时控制。

由 spawn 创建的实例拥有其生成的工作树。由 attach 创建的实例将当前工作树标记为外部。destroy --worktree 在停止或移除任何内容之前拒绝外部所有权；普通的 destroy 只移除 BranchLift 运行时状态。

branchlift exec 和显式启用的主机代理命令不是安全边界。branchlift sandbox run 在命令周围添加了一个加固的 Docker 边界，但它不是 VM 边界，并且它有意授予所选工作树和任何范围内的后端/密钥访问权限。Compose 应用服务保留其自身的镜像和 Compose 安全设置。参见 SECURITY.md 和 docs/SECURITY-AND-SECRETS.md。

存储行为

运行时状态位于仓库之外：

~/.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>/

使用 BRANCHLIFT_HOME 覆盖根目录。

复制策略顺序：

1. macOS APFS clonefile（cp -c）；

2. Linux reflink（cp --reflink=always）；

3. 安全递归复制回退。

每个就绪快照的卷树在其摘要清单写入后变为主机只读。配置恢复仅所有者写访问权限到克隆的运行时状态，从不世界写访问权限。每次重置都克隆到一个从未挂载过的卷代，并且仅在克隆验证后才切换生成的 Compose 覆盖文件。前一代在替换堆栈变得健康后被移除。这避免了 Docker Desktop 绑定缓存竞争，并且永远不会将半复制的重置暴露为活动路径。

在你的机器上测量克隆延迟与强制完整复制基线的对比：

branchlift benchmark dev --iterations 10

对于与数据库无关的固定测试，使用 npm run benchmark:synthetic -- --size-mib 256 --iterations 7。对于固定的 Docmost 比较，使用 npm run benchmark:docmost -- --dataset-mib 128 --iterations 3。

记录的 Docmost 结果故意不呈现为胜利：其真实的 APFS 状态克隆比完整复制快 2.51 倍，但完整的 HTTP 就绪路径是 0.82 倍，因为 Docker Desktop 启动绑定挂载的 PostgreSQL 状态更慢。在公开的 Linux Btrfs 运行中，512 MiB 合成克隆中位数为 31.25 毫秒，而强制完整复制为 600.95 毫秒，加速 19.23 倍。方法论、原始证据和阴性对照在 docs/BENCHMARKS.md 中。

开发

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

参见 docs/COMPATIBILITY.md、docs/EVIDENCE.md、docs/ARCHITECTURE.md、docs/SECURITY-AND-SECRETS.md、docs/REMOTE.md 和 CONTRIBUTING.md 以了解确切的支持合同和公共生命周期证据。

架构在 docs/ARCHITECTURE.md 中有文档说明。

社区

• 错误报告和功能建议：GitHub Issues

• 问题和展示：GitHub Discussions

• 贡献：CONTRIBUTING.md — 每个 PR 之前必须通过 npm run verify。

• 安全报告：SECURITY.md — 请使用私有安全公告而不是公开问题。

如果 BranchLift 为你节省了一次重新播种周期，请给仓库加星标——这是该类别中独立、非 VC 项目的主要发现信号。

许可证和来源

Apache-2.0。BranchLift 是一个原创实现。它受到工作树环境工具和数据库分支系统的公共行为和产品理念的启发，但不复制其源代码或声称其工作为己有。