尧图网页设计 
Gondolin 可编程文件系统 VFS 指南如何在 JavaScript 中自定义 AI 沙箱的磁盘行为【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolinGondolin 是一款专为 AI Agent 设计的 Linux micro-VM 沙箱其核心能力之一是可编程文件系统 VFSVirtual File System。通过 JavaScript 定义的 Provider你可以在不修改 Guest 镜像的前提下精确控制 AI 生成的代码能看到什么文件、能写到哪里。本文用最短的篇幅带你掌握 Gondolin VFS 的内置 Provider、影子层策略与自定义文件系统的全部玩法。为什么 AI 沙箱需要可编程文件系统AI Agent 经常需要在无人审核的情况下执行生成的代码。这些代码可能️ 试图读取你本地的.env密钥文件 误用宿主机的node_modules架构可能不匹配✍️ 意外污染你的真实工作目录传统的整个目录挂载进虚拟机方案做不到细粒度控制。Gondolin 的思路是把 Guest 的文件系统抽象为宿主机上的 JavaScript 对象每一次open、stat、read都会经过宿主侧的策略层。VFS 三层架构一次文件读操作发生了什么Gondolin 的 VFS 分为三层详见 docs/vfs.md层级位置职责1️⃣ Guest FUSE 文件系统虚拟机内部Guest 里的进程调用普通 POSIX API2️⃣ 宿主侧 RPC 翻译层宿主机把 VFS 操作转换为 RPC 调用3️⃣ Provider可叠加宿主机 JavaScript真正决定这个文件是什么Guest 进程 (cat /workspace/.env) │ FUSE ▼ Guest sandboxfs ──RPC──▶ 宿主 MountRouter ──▶ Provider 栈 ├─ ShadowProvider隐藏密钥 └─ RealFSProvider真实目录路由规则很简单vfs.mounts是一个绝对路径 → Provider的映射表多个挂载点共存时操作会被路由到最长匹配前缀的 Provider。这个逻辑实现在 host/src/vfs/mounts.ts 的MountRouterProvider中。5 分钟上手挂载你的第一个 Provider创建 VM 时只需在VM.create中传入vfs配置import { VM, MemoryProvider, RealFSProvider } from earendil-works/gondolin; const vm await VM.create({ vfs: { mounts: { /workspace: new RealFSProvider(/host/path/to/repo), // 共享真实目录 /scratch: new MemoryProvider(), // 内存草稿区 }, }, });一个细节Gondolin 实际上只挂载一次 FUSE默认挂载点/data再把各个配置项bind mount到目标位置。你可以通过fuseMount: /vfs修改底层挂载点完整说明见 docs/vfs.md。4 个内置 Provider覆盖 90% 的使用场景MemoryProvider内存草稿区✅ 快、可丢弃、与宿主机完全隔离✅ 适合代码生成的工作区、临时构建产物⚠️ VM 关闭即丢失不进入磁盘检查点RealFSProvider共享宿主机目录把宿主机目录暴露给 Guest读写直接作用于真实文件。安全特性值得注意阻止符号链接逃逸出暴露的目录fail-closed悬空符号链接在跟随式操作open/stat中一律被拒实现见 host/src/vfs/ 下的 RealFS 相关代码。ReadonlyProvider只读包装器用new ReadonlyProvider(backend)包一层所有写操作立即返回EROFS只读文件系统错误。源码仅 200 行出头是很好的 VFS 二次开发范本host/src/vfs/readonly.ts。// 挂载配置目录Guest 只能读 /config: new ReadonlyProvider(new RealFSProvider(./config))ShadowProvider最强大的影子层ShadowProvider是安全策略的核心武器源码在 host/src/vfs/shadow.ts。它按回调函数选择性地隐身某些路径读操作表现得像文件根本不存在ENOENT且从readdir目录列表中剔除写操作可拒绝writeMode: deny默认或重定向到内存层writeMode: tmpfs防符号链接绕过默认启用denySymlinkBypassln -s .env x cat x这种伎俩也会被拦截场景一隐藏密钥文件import { createShadowPathPredicate } from earendil-works/gondolin; const hideSecrets createShadowPathPredicate([/.env, /.npmrc]); const workspace new ShadowProvider(new RealFSProvider(repoDir), { shouldShadow: hideSecrets, // 写操作默认直接拒绝 });场景二隐藏宿主机的node_modules但允许 Guest 自己安装这是最实用的技巧之一用writeMode: tmpfs让 Guest 在内存里生成自己的node_modules完全不碰宿主机目录const noHostNodeModules new ShadowProvider(secrets, { shouldShadow: createShadowPathPredicate([/node_modules]), writeMode: tmpfs, // 写操作落入内存层 });同样适用于隐藏.git、.venv、dist等可能架构错配的大目录。VFS Hooks审计 Guest 的每一次文件访问不想写完整 Provider给vfs加上before/after钩子即可旁路观察或拦截所有操作vfs: { mounts: { /: new MemoryProvider() }, hooks: { before: (ctx) console.log(ctx.op, ctx.path), // open / read / stat / unlink ... after: (ctx) { /* 采集指标、记录审计日志 */ }, }, }钩子上下文包含操作名、路径、open flags、偏移量、写入数据甚至操作结果完整类型定义在 host/src/vfs/provider.ts。适合做安全审计、用量统计和调试意外的文件读取。进阶用 JavaScript 写一个自定义文件系统内置 Provider 不够时你可以自己实现一个合成文件系统——虚拟目录、动态内容生成、远程存储映射都可以。官方推荐两个基类VirtualProviderClass完整的读写 Provider 基类host/src/vfs/utils.tsReadonlyVirtualProvider只读场景专用只需实现openReadonlySync、statSync、readdirSync三个方法其余全部自动委托或返回EROFShost/src/vfs/readonly-virtual.ts真实项目中的自定义 Provider 示例可以参考 host/examples/magic-git-bash.ts。Provider 叠加的黄金法则Provider 天生可堆叠典型栈形如ShadowProvider(ShadowProvider(RealFSProvider(dir), 密钥策略), 构建产物策略)经验法则最敏感的安全策略如拦截密钥放在离真实宿主机文件系统最近的一层。避坑指南3 个最常见的 VFS 陷阱陷阱说明对策 意外隐藏 CA 证书Gondolin 默认把 MITM CA 注入/etc/gondolin/mitm/ca.crt不要用自己的 Provider 挂载到/etc/gondolin下自定义/挂载时注意保留系统信任链 检查点不含 VFS 数据磁盘检查点snapshot只捕获 root 磁盘VFS 数据存在 Provider 中需要持久化的产物用RealFSProvider挂到宿主机目录⏱️ 同步操作中用异步 Hook在openSync等路径上注册async钩子会直接抛错同步调用链中使用同步钩子函数总结Gondolin 的 VFS 把AI 代码能碰哪些文件这个安全问题变成了几个熟悉的 JavaScript 对象MemoryProvider→ 隔离草稿区RealFSProvider→ 安全共享真实目录ReadonlyProvider→ 一行代码实现只读ShadowProvider→ 隐藏密钥、隔离依赖还能放行 Guest 自建文件Hooks / 自定义 Provider→ 审计与完全可编程的磁盘行为完整 Provider 参考与更多配方阻止/.env、隐藏node_modules等请查阅官方文档 docs/vfs.md存储相关的 rootfs 模式与检查点说明见 docs/sdk-storage.md。掌握这套工具你就能让 AI 沙箱的磁盘行为完全可控、可审计。【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gondolin 可编程文件系统 VFS 指南：如何在 JavaScript 中自定义 AI 沙箱的磁盘行为
Gondolin 可编程文件系统 VFS 指南如何在 JavaScript 中自定义 AI 沙箱的磁盘行为【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolinGondolin 是一款专为 AI Agent 设计的 Linux micro-VM 沙箱其核心能力之一是可编程文件系统 VFSVirtual File System。通过 JavaScript 定义的 Provider你可以在不修改 Guest 镜像的前提下精确控制 AI 生成的代码能看到什么文件、能写到哪里。本文用最短的篇幅带你掌握 Gondolin VFS 的内置 Provider、影子层策略与自定义文件系统的全部玩法。为什么 AI 沙箱需要可编程文件系统AI Agent 经常需要在无人审核的情况下执行生成的代码。这些代码可能️ 试图读取你本地的.env密钥文件 误用宿主机的node_modules架构可能不匹配✍️ 意外污染你的真实工作目录传统的整个目录挂载进虚拟机方案做不到细粒度控制。Gondolin 的思路是把 Guest 的文件系统抽象为宿主机上的 JavaScript 对象每一次open、stat、read都会经过宿主侧的策略层。VFS 三层架构一次文件读操作发生了什么Gondolin 的 VFS 分为三层详见 docs/vfs.md层级位置职责1️⃣ Guest FUSE 文件系统虚拟机内部Guest 里的进程调用普通 POSIX API2️⃣ 宿主侧 RPC 翻译层宿主机把 VFS 操作转换为 RPC 调用3️⃣ Provider可叠加宿主机 JavaScript真正决定这个文件是什么Guest 进程 (cat /workspace/.env) │ FUSE ▼ Guest sandboxfs ──RPC──▶ 宿主 MountRouter ──▶ Provider 栈 ├─ ShadowProvider隐藏密钥 └─ RealFSProvider真实目录路由规则很简单vfs.mounts是一个绝对路径 → Provider的映射表多个挂载点共存时操作会被路由到最长匹配前缀的 Provider。这个逻辑实现在 host/src/vfs/mounts.ts 的MountRouterProvider中。5 分钟上手挂载你的第一个 Provider创建 VM 时只需在VM.create中传入vfs配置import { VM, MemoryProvider, RealFSProvider } from earendil-works/gondolin; const vm await VM.create({ vfs: { mounts: { /workspace: new RealFSProvider(/host/path/to/repo), // 共享真实目录 /scratch: new MemoryProvider(), // 内存草稿区 }, }, });一个细节Gondolin 实际上只挂载一次 FUSE默认挂载点/data再把各个配置项bind mount到目标位置。你可以通过fuseMount: /vfs修改底层挂载点完整说明见 docs/vfs.md。4 个内置 Provider覆盖 90% 的使用场景MemoryProvider内存草稿区✅ 快、可丢弃、与宿主机完全隔离✅ 适合代码生成的工作区、临时构建产物⚠️ VM 关闭即丢失不进入磁盘检查点RealFSProvider共享宿主机目录把宿主机目录暴露给 Guest读写直接作用于真实文件。安全特性值得注意阻止符号链接逃逸出暴露的目录fail-closed悬空符号链接在跟随式操作open/stat中一律被拒实现见 host/src/vfs/ 下的 RealFS 相关代码。ReadonlyProvider只读包装器用new ReadonlyProvider(backend)包一层所有写操作立即返回EROFS只读文件系统错误。源码仅 200 行出头是很好的 VFS 二次开发范本host/src/vfs/readonly.ts。// 挂载配置目录Guest 只能读 /config: new ReadonlyProvider(new RealFSProvider(./config))ShadowProvider最强大的影子层ShadowProvider是安全策略的核心武器源码在 host/src/vfs/shadow.ts。它按回调函数选择性地隐身某些路径读操作表现得像文件根本不存在ENOENT且从readdir目录列表中剔除写操作可拒绝writeMode: deny默认或重定向到内存层writeMode: tmpfs防符号链接绕过默认启用denySymlinkBypassln -s .env x cat x这种伎俩也会被拦截场景一隐藏密钥文件import { createShadowPathPredicate } from earendil-works/gondolin; const hideSecrets createShadowPathPredicate([/.env, /.npmrc]); const workspace new ShadowProvider(new RealFSProvider(repoDir), { shouldShadow: hideSecrets, // 写操作默认直接拒绝 });场景二隐藏宿主机的node_modules但允许 Guest 自己安装这是最实用的技巧之一用writeMode: tmpfs让 Guest 在内存里生成自己的node_modules完全不碰宿主机目录const noHostNodeModules new ShadowProvider(secrets, { shouldShadow: createShadowPathPredicate([/node_modules]), writeMode: tmpfs, // 写操作落入内存层 });同样适用于隐藏.git、.venv、dist等可能架构错配的大目录。VFS Hooks审计 Guest 的每一次文件访问不想写完整 Provider给vfs加上before/after钩子即可旁路观察或拦截所有操作vfs: { mounts: { /: new MemoryProvider() }, hooks: { before: (ctx) console.log(ctx.op, ctx.path), // open / read / stat / unlink ... after: (ctx) { /* 采集指标、记录审计日志 */ }, }, }钩子上下文包含操作名、路径、open flags、偏移量、写入数据甚至操作结果完整类型定义在 host/src/vfs/provider.ts。适合做安全审计、用量统计和调试意外的文件读取。进阶用 JavaScript 写一个自定义文件系统内置 Provider 不够时你可以自己实现一个合成文件系统——虚拟目录、动态内容生成、远程存储映射都可以。官方推荐两个基类VirtualProviderClass完整的读写 Provider 基类host/src/vfs/utils.tsReadonlyVirtualProvider只读场景专用只需实现openReadonlySync、statSync、readdirSync三个方法其余全部自动委托或返回EROFShost/src/vfs/readonly-virtual.ts真实项目中的自定义 Provider 示例可以参考 host/examples/magic-git-bash.ts。Provider 叠加的黄金法则Provider 天生可堆叠典型栈形如ShadowProvider(ShadowProvider(RealFSProvider(dir), 密钥策略), 构建产物策略)经验法则最敏感的安全策略如拦截密钥放在离真实宿主机文件系统最近的一层。避坑指南3 个最常见的 VFS 陷阱陷阱说明对策 意外隐藏 CA 证书Gondolin 默认把 MITM CA 注入/etc/gondolin/mitm/ca.crt不要用自己的 Provider 挂载到/etc/gondolin下自定义/挂载时注意保留系统信任链 检查点不含 VFS 数据磁盘检查点snapshot只捕获 root 磁盘VFS 数据存在 Provider 中需要持久化的产物用RealFSProvider挂到宿主机目录⏱️ 同步操作中用异步 Hook在openSync等路径上注册async钩子会直接抛错同步调用链中使用同步钩子函数总结Gondolin 的 VFS 把AI 代码能碰哪些文件这个安全问题变成了几个熟悉的 JavaScript 对象MemoryProvider→ 隔离草稿区RealFSProvider→ 安全共享真实目录ReadonlyProvider→ 一行代码实现只读ShadowProvider→ 隐藏密钥、隔离依赖还能放行 Guest 自建文件Hooks / 自定义 Provider→ 审计与完全可编程的磁盘行为完整 Provider 参考与更多配方阻止/.env、隐藏node_modules等请查阅官方文档 docs/vfs.md存储相关的 rootfs 模式与检查点说明见 docs/sdk-storage.md。掌握这套工具你就能让 AI 沙箱的磁盘行为完全可控、可审计。【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考