feat: add portable environment bundles

- support incremental init and rootfs/bundle export-import
- preserve hardlinks and metadata across environment migration
- add a rootless rollback demo and sharpen project positioning

Author: css521

CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Added
+- **Incremental init** (`agentenv init --sync --from <dir|/>` / `--tarball`):
+  overlays new/changed files from the source onto the current environment and
+  commits a **child** of HEAD, instead of the one-shot root-node behavior. This
+  folds in packages/config that landed on the container's host `/` *after* the
+  first seed (an entrypoint step or `docker exec`), which the sandboxed agent —
+  running in `work/current` — otherwise never sees. `--delete` additionally
+  mirrors removals (drops files absent from the source); the default is additive.
+- **Environment export/import** (`agentenv export` / `agentenv import`):
+  - `export [ref] --format rootfs` — a node's rootfs as a flat `.tar(.gz)`, to
+    `-o <file>` or `-o -` (stdout), for `docker import -` / `FROM scratch; ADD`.
+    Cleaner than `docker commit`, which would also capture agentenv's node store.
+  - `export --format agentenv [--all]` — an **agentenv bundle**: a self-describing
+    archive (`manifest.json` + per-node rootfs) that moves a whole environment
+    between agentenv instances. `--all` carries the entire commit-DAG, tags and
+    history; without it, a single self-contained snapshot.
+  - `import <tar|URL>` — auto-detects the input: a flat rootfs tar becomes one
+    node under HEAD; a snapshot bundle adds its node; a whole-repo bundle restores
+    the full DAG into an empty `AGENTENV_ROOT`.
+  - New `image.TarDir`/`TarInto` (the inverse of `extractTar`, hardlink-aware and
+    PAX-timestamped so bundles reproduce the on-disk store exactly) and
+    `internal/repo/bundle.go` (the bundle manifest + pack/restore).
+
 ## [0.3.1] - 2026-07-02
 
 ### Added

DESIGN.md

@@ -15,6 +15,10 @@ agent from the restored environment.
 - **Language**: Go. **No mandatory base image** — bring your own rootfs via
   `init --from <dir|/>` (the common path: wrap an existing container image)
   or `init --tarball <path|URL>` (for air-gapped / scripted seeding).
+  `init --sync` re-seeds incrementally after start; `export`/`import` move an
+  environment out to a Docker image (flat rootfs tar) or between agentenv
+  instances (an **agentenv bundle** = `manifest.json` + per-node rootfs,
+  hardlink-shared and PAX-timestamped so it faithfully reproduces the store).
 - **Minimal deps**:
   - `containerd/btrfs/v2` — cgo, **only** when built `-tags btrfs`.
   - `creack/pty` + `golang.org/x/sys` + `golang.org/x/term` — interactive
@@ -116,6 +120,9 @@ btrfs backend, when used, requires `AGENTENV_ROOT` to be on a btrfs fs.
 | Command            | Effect |
 |--------------------|--------|
 | `init --from <dir>` / `init --tarball <p>` | seed root from a directory tree (one-time copy) or extract a `.tar(.gz)`; freeze as the root node |
+| `init --sync --from <dir>` / `--tarball <p>` | incremental: overlay the source onto `work/current` and freeze a **child** of HEAD (folds in files added to the host after the first seed); `--delete` also mirrors removals |
+| `export [ref] --format rootfs\|agentenv [--all]` | write a node's rootfs as a flat tar (for `docker import` / migration), or an agentenv **bundle** (`--all` = whole DAG + tags + history; else one self-contained snapshot) |
+| `import <tar\|URL>` | auto-detected: flat rootfs → one node under HEAD; snapshot bundle → its node; whole-repo bundle → restore the full DAG into an empty root |
 | `supervise -- <cmd>` | start the inner agent under auto-capture; survives rollbacks (relaunches the agent from the restored env) |
 | `daemon`           | serve the newline-JSON protocol on the unix socket (for orchestrators / `ctl`) |
 | `mcp`              | MCP server over stdio (Claude Code / any MCP host); bridges tool calls to the daemon socket |

Makefile

@@ -3,6 +3,7 @@
 #
 # Cheat sheet:
 #   make help              list every target with a short description
+#   make demo              watch agentenv undo whole-system changes, rootless
 #   make build             cross-compile a Linux static binary into ./bin/
 #   make test              cross-platform unit tests (dag, image, ...)
 #   make vet               gofmt check + go vet
@@ -13,13 +14,20 @@
 
 GOOS_LINUX ?= linux
 GOARCH     ?= $(shell uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/;s/arm64/arm64/')
-GOPROXY    ?= $(shell go env GOPROXY)
+GOPROXY    ?= $(shell if command -v go >/dev/null 2>&1; then go env GOPROXY; else printf '%s' 'https://proxy.golang.org,direct'; fi)
 
-.PHONY: help build test vet verify-rootless verify-btrfs verify-supervise verify-mcp verify-rollback openapi-snapshot dev-shell dev-shell-stop clean
+.PHONY: help demo build test vet verify-rootless verify-btrfs verify-supervise verify-mcp verify-rollback openapi-snapshot dev-shell dev-shell-stop clean
 
 help:
 	@awk 'BEGIN{FS=":.*##"; printf "Targets:\n"} /^[a-zA-Z_-]+:.*##/ { printf "  %-22s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
 
+demo: ## rootless Docker demo: break the whole environment, then rewind it
+	docker run --rm --user 1001:1001 --security-opt seccomp=unconfined \
+	  -v "$$PWD":/src:ro \
+	  -e GOFLAGS=-mod=mod -e GOPROXY="$(GOPROXY)" \
+	  -e CGO_ENABLED=0 -e GOCACHE=/tmp/gocache -e GOMODCACHE=/tmp/gomodcache \
+	  -w /src golang:1.26 bash /src/scripts/demo-rootless.sh
+
 build: ## cross-compile a Linux static binary (./bin/agentenv-<arch>)
 	@mkdir -p bin
 	GOOS=$(GOOS_LINUX) GOARCH=$(GOARCH) CGO_ENABLED=0 go build -o bin/agentenv-$(GOARCH) .

README.md

@@ -4,11 +4,15 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Go Reference](https://pkg.go.dev/badge/github.com/css521/agentenv.svg)](https://pkg.go.dev/github.com/css521/agentenv)
 
-A **self-hostable, rewindable virtual environment for agents** that runs even in a
-locked-down Kubernetes pod (non-root, no `privileged`, no special capabilities).
-The environment versions itself automatically (zero agent intrusion), can roll
-back to **any node**, and can **branch** so an agent explores several approaches in
-parallel branches and keeps the winner.
+**Git-style time travel for AI agents.** agentenv automatically snapshots an
+agent's entire Linux environment — source files, installed packages, tools, and
+system configuration — so it can rewind to any past node or fork several
+approaches and keep the winner.
+
+It is self-hosted and rootless: on Linux/Kubernetes nodes that allow
+unprivileged user namespaces, the default backend runs as a non-root user
+without `privileged`, extra Linux capabilities, `/dev/kvm`, btrfs, or FUSE. The
+agent runs unmodified, and MCP lets it inspect and rewind its own environment.
 
 ![Claude Code deletes its own binary, then rolls the environment back via MCP and recovers it](./docs/claude-rewind.gif)
 
@@ -19,12 +23,27 @@ parallel branches and keeps the winner.
 > Reproducible from [`examples/claude-code/`](./examples/claude-code/); re-record
 > the GIF with [`scripts/record-claude-tui.sh`](./scripts/record-claude-tui.sh).
 
+## Try the rollback
+
+Run a real rootless demo in Docker. It creates a working system binary, deletes
+it and changes `/etc`, then rewinds the whole environment and verifies both
+changes were undone. No `privileged` container or extra capabilities are used.
+
+```bash
+git clone https://github.com/css521/agentenv.git
+cd agentenv
+make demo
+```
+
+The first run downloads the Go build image and a minimal Ubuntu rootfs. The demo
+runs as uid 1001 and uses the same copy backend intended for restricted pods.
+
 See [`DESIGN.md`](./DESIGN.md) for the architecture.
 
 ## Install
 
 ```bash
-# Default static binary (copy/rootless backend) — runs anywhere, incl. restricted pods:
+# Linux static binary (copy/rootless backend) — including restricted pods:
 go install github.com/css521/agentenv@latest
 
 # From source:
@@ -34,7 +53,7 @@ CGO_ENABLED=1 go build -tags btrfs -o agentenv .     # optional btrfs fast path
 ```
 
 Prebuilt binaries are attached to each [release](https://github.com/css521/agentenv/releases).
-Multi-arch container images at `ghcr.io/css521/agentenv` (`:latest` or `:vX.Y.Z`).
+Multi-arch container images are at `ghcr.io/css521/agentenv` (`:latest` or `:X.Y.Z`).
 
 ## Why it's different
 
@@ -95,6 +114,16 @@ agentenv upgrade [--version X]  zero-downtime hot-upgrade of a running daemon (r
 # setup / history / inspection
 agentenv init --from <dir|/> | --tarball <path|URL>
                                 seed root from an existing dir, or extract a tar(.gz)
+agentenv init --sync --from <dir|/> | --tarball <p> [-m msg] [--delete]
+                                incremental: overlay changes onto the env, commit a child node
+                                (folds in files added to the host AFTER the first seed);
+                                --delete also removes files gone from the source (mirror)
+agentenv export [ref] -o <file|-> [--format rootfs|agentenv] [--all] [--gzip]
+                                rootfs = flat tar of a node (for `docker import` / migration);
+                                agentenv = self-describing bundle: --all = whole repo + history,
+                                else a single self-contained snapshot
+agentenv import <tar|URL> [-m msg]
+                                bring in a rootfs tar OR an agentenv bundle (auto-detected)
 agentenv commit -m "msg"        manual snapshot (auto-capture usually does this)
 agentenv checkout <ref>         roll the whole env back to any node (accepts tag/prefix)
 agentenv delete <ref>           remove a node (children re-parent; HEAD/only-node refused)
@@ -185,6 +214,45 @@ kubectl exec my-agent -- agentenv ctl log
 kubectl exec my-agent -- agentenv ctl checkout <node-id>   # roll the whole env back
 ```
 
+## Incremental init, migration & sharing
+
+Two lifecycle needs beyond the one-time `init`:
+
+**Fold in files added after startup.** The first `init --from /` is a one-time
+copy, so packages/config downloaded into the container's real `/` *afterwards*
+(an entrypoint step, or a `docker exec`) never reach the sandboxed env. Re-run
+init with `--sync` to overlay them and commit a child node:
+
+```bash
+agentenv init --sync --from /                 # pick up new/changed files on the host
+agentenv init --sync --from / --delete        # also drop files removed from the source (mirror)
+```
+
+**Migrate the environment to another Docker image** — export a node's rootfs as a
+flat tar (no `docker commit`, which would also capture agentenv's own node store):
+
+```bash
+agentenv export -o - | docker import - my-image:tag      # stream straight into docker
+agentenv export -o rootfs.tar                            # or, in a Dockerfile:
+#   FROM scratch
+#   ADD rootfs.tar /
+```
+
+**Move a whole environment (with history) between agentenv instances** — the
+agentenv bundle format carries the commit-DAG, tags and every node's rootfs:
+
+```bash
+agentenv export --format agentenv --all -o env.agentenv   # whole repo + history
+agentenv export --format agentenv -o snap.agentenv        # one self-contained snapshot
+
+AGENTENV_ROOT=/fresh agentenv import env.agentenv         # restore into an empty root
+agentenv import snap.agentenv                             # or add a snapshot under HEAD
+```
+
+`import` auto-detects the input: a plain rootfs tar becomes one node under HEAD; a
+snapshot bundle adds its node; a whole-repo bundle restores the full DAG into an
+empty `AGENTENV_ROOT`.
+
 ## Agent integration (socket API)
 
 `agentenv daemon` serves a newline-delimited JSON protocol over a unix socket, so

design_zh.md

@@ -0,0 +1,162 @@
+# agentenv — 给 AI Agent 用的"后悔药"环境
+
+## 一句话说清楚
+
+agentenv 是一个沙箱工具。AI Agent 在里面干活时，**环境会自动保存每一步的快照**。搞砸了？一条命令就能回到之前任意一个"存档点"，就像游戏里的存档/读档。
+
+Agent 本身完全不需要做任何适配——它甚至不知道 agentenv 的存在。
+
+---
+
+## 它解决什么问题？
+
+AI Agent 在执行编程任务时，经常需要安装依赖、修改配置文件、执行 shell 命令。这些操作有可能把环境搞坏——装错了包、改坏了配置、执行了有副作用的命令。
+
+传统方案是重建整个环境，代价很高。agentenv 的做法是：**环境随时可以"倒带"回去**，就像录像机的回放功能。
+
+---
+
+## 核心概念
+
+### 快照（Snapshot）
+
+每次文件系统发生变化（不管是 Agent 执行命令还是手动编辑文件），agentenv 都会自动拍一个快照。快照是只读的，保存了那个时刻文件系统的完整状态。
+
+你可以把它想象成 Git 的 commit，但记录的不是代码仓库，而是**整个操作系统的文件系统**。
+
+### 回滚（Rollback）
+
+回滚就是"读档"：把文件系统恢复到某个快照的状态，同时终止环境内的所有进程，然后重新启动 Agent。
+
+**什么能回滚**：文件系统的一切——安装的软件、配置文件、临时文件。
+
+**什么不能回滚**：已经发出去的网络请求、已经过去的时间。发出去的 HTTP 请求收不回来。
+
+### 锦标赛模式（Tournament）
+
+当需要尝试多个方案时，agentenv 可以同时开 N 个独立的环境副本，每个副本跑一个候选方案并执行测试，自动保留第一个通过测试的方案。
+
+类似于同时开 N 个平行世界，选最好的那个。
+
+---
+
+## 架构：三层设计
+
+agentenv 分三层，**Agent 只感知到最里面一层**：
+
+```
+┌─────────────────────────────────────────────────────┐
+│  第 1 层：启动器（Launcher）                           │
+│  负责创建沙箱，只在启动时运行一次。                       │
+│  实际就是 docker run 或 k8s pod 的启动命令。              │
+│                                                     │
+│  ┌─────────────────────────────────────────────────┐ │
+│  │  第 2 层：管理者（Supervise）                      │ │
+│  │  常驻后台进程。负责监控文件变化、自动拍快照、           │ │
+│  │  执行回滚。它自己永远不会被回滚。                     │ │
+│  │                                                 │ │
+│  │  ┌─────────────────────────────────────────────┐ │ │
+│  │  │  第 3 层：内部环境                            │ │ │
+│  │  │  Agent 实际运行的地方。                        │ │ │
+│  │  │  Shell、软件包、Agent 进程，都在这里。          │ │ │
+│  │  │  回滚 = 杀掉这里的进程 + 恢复文件系统。        │ │ │
+│  │  └─────────────────────────────────────────────┘ │ │
+│  └─────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+```
+
+为什么要分层？因为"管理回滚的人"不能自己也被回滚，否则就没人来执行恢复操作了。所以管理者（第 2 层）始终待在安全区，只有内部环境（第 3 层）会被回滚。
+
+---
+
+## 两种存储后端
+
+agentenv 支持两种方式来管理快照，启动时自动选择合适的那个：
+
+| | copy 模式（默认） | btrfs 模式 |
+|---|---|---|
+| **适用场景** | 大多数环境，包括受限的 K8s Pod | 有 root 权限且使用 btrfs 文件系统 |
+| **是否需要 root** | 不需要 | 需要 |
+| **快照速度** | 通过硬链接共享不变的文件，只复制有变化的部分。如果文件系统支持 reflink（如 XFS、ZFS），速度接近瞬时 | 瞬时（利用 btrfs 的写时复制） |
+| **编译方式** | 默认，纯 Go 静态编译 | 需要加 `-tags btrfs`，依赖 cgo |
+
+简单理解：copy 模式就像"复制文件夹但跳过没改的文件"，btrfs 模式就像"文件系统帮你管理副本，改了才占空间"。
+
+---
+
+## 磁盘上长什么样
+
+```
+/agentfs/                          ← 默认根目录
+  ├── nodes/                       ← 所有快照存在这里
+  │   ├── abc123/                  ← 快照 1（只读）
+  │   └── def456/                  ← 快照 2（只读）
+  ├── work/current/                ← Agent 当前工作的目录（可读写）
+  ├── meta.json                    ← 快照之间的关系（谁是谁的父节点）
+  ├── agentenv.sock                ← 管理用的通信接口
+  └── agentenv.lock                ← 防止多个进程同时操作
+```
+
+---
+
+## 常用命令速查
+
+### 初始化与数据交换
+
+| 命令 | 做什么 |
+|------|--------|
+| `agentenv init --from <目录>` | 从一个已有目录创建初始环境 |
+| `agentenv init --tarball <文件>` | 从压缩包创建初始环境 |
+| `agentenv init --sync --from <目录>` | 增量同步：把目录中新增的文件合并进来 |
+| `agentenv export` | 把环境导出为 tar 包（可以给 `docker import` 用） |
+| `agentenv import <文件>` | 导入一个环境包 |
+
+### 运行与管理
+
+| 命令 | 做什么 |
+|------|--------|
+| `agentenv supervise -- <命令>` | 启动 Agent 并自动管理快照和回滚 |
+| `agentenv daemon` | 启动后台守护进程，通过 socket 接受管理命令 |
+| `agentenv mcp` | 启动 MCP 服务器，让 Claude Code 等工具通过 MCP 协议来管理环境 |
+| `agentenv exec -- <命令>` | 在环境内执行一次性命令（适合脚本和 CI） |
+
+### 快照与回滚
+
+| 命令 | 做什么 |
+|------|--------|
+| `agentenv commit -m "说明"` | 手动创建一个快照（通常不需要，系统会自动创建） |
+| `agentenv checkout <快照ID>` | 回滚到指定快照 |
+| `agentenv tag <名字> <快照ID>` | 给快照取一个好记的名字 |
+| `agentenv log` | 查看快照历史 |
+| `agentenv status` | 查看当前环境状态 |
+| `agentenv diff` | 查看当前环境和某个快照的差异 |
+| `agentenv gc` | 清理不再需要的旧快照，释放磁盘空间 |
+
+### 高级功能
+
+| 命令 | 做什么 |
+|------|--------|
+| `agentenv tournament --test "测试命令" -- "方案1" "方案2"` | 并行尝试多个方案，自动选出通过测试的那个 |
+| `agentenv ctl <操作>` | 在 Agent 运行时从外部发送管理命令（不会打断 Agent） |
+
+---
+
+## 回滚流程详解
+
+当执行 `checkout` 回滚时，实际发生的事情：
+
+1. **终止进程** — 杀掉内部环境里所有正在运行的程序
+2. **恢复文件系统** — 从目标快照还原 `work/current` 目录
+3. **更新指针** — 把 HEAD 指向目标快照，安全写入元数据
+4. **重启 Agent** — 如果在 `supervise` 模式下，自动从恢复后的环境重新启动 Agent
+
+整个过程中，管理者进程（supervise）始终在线，不受影响。
+
+---
+
+## 需要注意的限制
+
+- **网络操作不可逆**：已发出的 API 请求、已发送的消息无法撤回，这是物理限制
+- **不是安全隔离**：agentenv 提供的是环境隔离，不是安全沙箱。如果要运行不信任的代码，应该再套一层虚拟机
+- **Linux 限定**：核心功能依赖 Linux 命名空间，macOS 上只能编辑代码，实际运行需要 Linux 环境
+- **受限环境的额外要求**：在某些安全策略较严格的 Linux 环境（如 Ubuntu 22.04+ 的 AppArmor）中，可能需要额外放宽安全策略才能运行