尧图网站建设 
用Gondolin打造自定义AI沙箱镜像从Alpine构建流水线到OCI rootfs的完整流程【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolinGondolin 是一个运行在本地 Linux micro-VM 中的 AI Agent 沙箱由 TypeScript 控制面驱动可程序化管控网络与文件系统策略。如果你想让 AI Agent 在你机器上安全执行代码Gondolin 自定义沙箱镜像就是绕不开的一环它允许你通过一条 Alpine 构建流水线或任意 OCI 容器镜像生成内核、initramfs 和 rootfs 三大启动工件为 AI 沙箱预装 Python、Node、浏览器等一切运行环境。本文将带你走通从配置到运行的完整流程。为什么需要自定义 AI 沙箱镜像默认的alpine-base镜像只带了 Node.js、Python3、SSH 等基础组件。而真实的 AI Agent 场景往往需要 预装特定语言的运行时与依赖如llm推理框架、pip 包 在沙箱里跑 Chromium 等无头浏览器⚡ 做最小化裁剪加快启动速度 用 Debian/Ubuntu 等发行版替代 Alpine 用户态Gondolin 的gondolin build命令正是为此设计它的完整文档在 docs/custom-images.md。构建前置安装构建环境构建自定义镜像只需几个常用宿主工具无需安装 Zig工具用途cpio制作 initramfs 压缩包lz4initramfs 压缩e2fsprogs创建/扩展 ext4 rootfs 镜像Docker 或 Podman可选拉取并导出 OCI rootfs 镜像# Debian / Ubuntu sudo apt install lz4 cpio e2fsprogs # macOS brew install lz4 e2fsprogs沙箱助手二进制sandboxd、sandboxfs、sandboxssh、sandboxingress由构建流程自动下载并缓存无需手动处理。相关解析逻辑见 host/src/build/sandbox-helpers.ts。生成构建配置一条命令起步最快捷的方式是生成默认配置再按需修改gondolin build --init-config build-config.json生成的 JSON 配置包含五大核心区块arch/distro目标架构aarch64或x86_64与发行版当前支持 Alpinealpine版本、内核包、rootfsPackagesrootfs 安装包列表oci可选的 OCI 镜像源见下文postBuild构建后拷贝文件与执行命令env烘焙进镜像的默认环境变量注意切勿存放真实密钥官方内置镜像的构建配置可以直接参考 images/alpine-base.json它是发布版alpine-base镜像的配方。Alpine 构建流水线三条产物线一次看懂执行gondolin build --config build-config.json --output ./my-assets后流水线核心实现在 host/src/build/alpine.ts容器化逻辑在 host/src/build/container.ts会并行产出两组启动工件my-assets/ manifest.json # 构建元数据 SHA-256 校验和 buildId vmlinuz-virt # Linux 内核 initramfs.cpio.lz4 # 压缩 initramfs rootfs.ext4 # 根文件系统镜像 krun-kernel # libkrun 后端兼容内核 krun-empty-initrd # krun 启动用空 initrd流水线内部大致分三步拉包解包—— 按rootfsPackages从 Alpine 源下载 APK解出用户态文件制作工件—— 打包 initramfscpiolz4用mke2fs创建 ext4 根文件系统写入 manifest—— 记录校验和与确定性buildId供快照/检查点机制定位资产构建完成后建议立即校验gondolin build --verify ./my-assetspostBuild 定制给沙箱注入 AI 能力postBuild是在 APK 解包后、镜像封盘前的自由发挥区支持两种能力copy把宿主机文件拷入镜像如把一个打包好的工具塞进/tmpcommands在 chroot 环境里按顺序执行的 shell 命令以官方的 LLM 示例 host/examples/llm.json 为例它先安装python3和py3-pip再用一条 postBuild 命令装好推理框架postBuild: { commands: [ pip3 install --break-system-packages llm llm-anthropic ] }一条命令构建即可得到一个带 LLM 工具的 AI 沙箱gondolin build --config host/examples/llm.json --output ./llm-assets GONDOLIN_GUEST_DIR./llm-assets gondolin exec -- llm --help macOS 上带postBuild.commands的构建会自动走容器执行 chroot 命令原生 Linux 上则需要 root 权限或使用container.forcetrue。更复杂的场景Chromium 沙箱官方的浏览器示例 host/examples/chromium.json 展示了两个进阶用法在rootfsPackages中加入chromium、mesa-dri-gallium、font-noto、xvfb-run等包通过init.rootfsInitExtra指定额外的 init 脚本对应 host/examples/chromium-init-extra.sh在sandboxd启动前完成 Xvfb 等环境准备配合--tag browser-use:latest给镜像打标签后即可被browser-use.ts这类 Agent 脚本通过 ingress 网关驱动——这是AI 在沙箱里操作真实浏览器的完整链路。跨发行版方案用 OCI rootfs 替代 Alpine 用户态不想局限于 AlpineGondolin 支持直接用任意 OCI 镜像Docker Hub / GHCR / 私有仓库作为rootfs 基座。原理见 docs/custom-images.md 的 OCI 一节实现代码在 host/src/alpine/oci.ts┌─────────────────────────────────────────────┐ │ Boot 层仍是 Alpine内核包 内核镜像 initramfs │ ├─────────────────────────────────────────────┤ │ Rootfs 层来自 OCIDebian/Ubuntu 用户态文件系统 │ └─────────────────────────────────────────────┘也就是说OCI 模式只替换根文件系统内容启动工件仍由 Alpine 组件组装。参考官方示例 host/examples/oci-debian.json{ arch: aarch64, distro: alpine, oci: { image: docker.io/library/debian:bookworm-slim, pullPolicy: if-not-present } }执行gondolin build --config host/examples/oci-debian.json --output ./oci-assets后构建器会通过 Docker/Podman 拉取镜像、导出 tar 并保留文件 UID/GID 属主信息最终得到一台内核是 Alpine、用户态是 Debian的混合沙箱。几个实用细节设置oci后alpine.rootfsPackages会被忽略rootfs 内容完全来自 OCI 镜像导出的 rootfs 必须包含/bin/sh否则需要提供自定义init.rootfsInitpullPolicy可选if-not-present默认、always、never三种拉取策略跨架构构建与使用自定义镜像构建机与目标架构不一致时直接加--arch即可缺原生工具时会自动改用容器构建# 在 Apple Silicon 上构建 x86_64 镜像 gondolin build --arch x86_64 --config build-config.json --output ./x64-assets构建产物有三种使用方式环境变量GONDOLIN_GUEST_DIR./my-assets gondolin bashCLI 标签构建时加--tag my-image:latest之后按镜像名引用SDKVM.create({ sandbox: { imagePath: ./my-assets } })指向资产目录完整的 CLI 参数说明见 docs/cli.md。常见问题速查症状解决方案mke2fs: command not found安装e2fsprogsmacOS 上确认其在 PATH 中brew --prefix e2fsprogsOCI 构建缺debugfsDebian/Ubuntu 的e2fsprogs已包含Alpine 宿主持需装e2fsprogs-extra构建超时 / VM 不启动确认架构匹配Apple Silicon 用aarch64x86_64 Linux 用x86_64包找不到Alpine 包分散在main与community仓库两者默认均已启用镜像过大精简rootfsPackages、选用更小的linux-virt内核、固定rootfs.sizeMb总结Gondolin 自定义沙箱镜像的核心思路是配方即代码一份 JSON 配置Alpine 包列表 postBuild 命令 可选 OCI 基座就能生成一套带校验和、可复现、可跨架构的 micro-VM 启动工件。无论是给 AI Agent 装一个推理框架还是造一个带 Chromium 的浏览器沙箱都只需几十行的配置差异。下一步可以阅读 host/src/build/ 下的流水线源码或 docs/architecture.md 了解控制面与沙箱的通信机制。【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用Gondolin打造自定义AI沙箱镜像：从Alpine构建流水线到OCI rootfs的完整流程
用Gondolin打造自定义AI沙箱镜像从Alpine构建流水线到OCI rootfs的完整流程【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolinGondolin 是一个运行在本地 Linux micro-VM 中的 AI Agent 沙箱由 TypeScript 控制面驱动可程序化管控网络与文件系统策略。如果你想让 AI Agent 在你机器上安全执行代码Gondolin 自定义沙箱镜像就是绕不开的一环它允许你通过一条 Alpine 构建流水线或任意 OCI 容器镜像生成内核、initramfs 和 rootfs 三大启动工件为 AI 沙箱预装 Python、Node、浏览器等一切运行环境。本文将带你走通从配置到运行的完整流程。为什么需要自定义 AI 沙箱镜像默认的alpine-base镜像只带了 Node.js、Python3、SSH 等基础组件。而真实的 AI Agent 场景往往需要 预装特定语言的运行时与依赖如llm推理框架、pip 包 在沙箱里跑 Chromium 等无头浏览器⚡ 做最小化裁剪加快启动速度 用 Debian/Ubuntu 等发行版替代 Alpine 用户态Gondolin 的gondolin build命令正是为此设计它的完整文档在 docs/custom-images.md。构建前置安装构建环境构建自定义镜像只需几个常用宿主工具无需安装 Zig工具用途cpio制作 initramfs 压缩包lz4initramfs 压缩e2fsprogs创建/扩展 ext4 rootfs 镜像Docker 或 Podman可选拉取并导出 OCI rootfs 镜像# Debian / Ubuntu sudo apt install lz4 cpio e2fsprogs # macOS brew install lz4 e2fsprogs沙箱助手二进制sandboxd、sandboxfs、sandboxssh、sandboxingress由构建流程自动下载并缓存无需手动处理。相关解析逻辑见 host/src/build/sandbox-helpers.ts。生成构建配置一条命令起步最快捷的方式是生成默认配置再按需修改gondolin build --init-config build-config.json生成的 JSON 配置包含五大核心区块arch/distro目标架构aarch64或x86_64与发行版当前支持 Alpinealpine版本、内核包、rootfsPackagesrootfs 安装包列表oci可选的 OCI 镜像源见下文postBuild构建后拷贝文件与执行命令env烘焙进镜像的默认环境变量注意切勿存放真实密钥官方内置镜像的构建配置可以直接参考 images/alpine-base.json它是发布版alpine-base镜像的配方。Alpine 构建流水线三条产物线一次看懂执行gondolin build --config build-config.json --output ./my-assets后流水线核心实现在 host/src/build/alpine.ts容器化逻辑在 host/src/build/container.ts会并行产出两组启动工件my-assets/ manifest.json # 构建元数据 SHA-256 校验和 buildId vmlinuz-virt # Linux 内核 initramfs.cpio.lz4 # 压缩 initramfs rootfs.ext4 # 根文件系统镜像 krun-kernel # libkrun 后端兼容内核 krun-empty-initrd # krun 启动用空 initrd流水线内部大致分三步拉包解包—— 按rootfsPackages从 Alpine 源下载 APK解出用户态文件制作工件—— 打包 initramfscpiolz4用mke2fs创建 ext4 根文件系统写入 manifest—— 记录校验和与确定性buildId供快照/检查点机制定位资产构建完成后建议立即校验gondolin build --verify ./my-assetspostBuild 定制给沙箱注入 AI 能力postBuild是在 APK 解包后、镜像封盘前的自由发挥区支持两种能力copy把宿主机文件拷入镜像如把一个打包好的工具塞进/tmpcommands在 chroot 环境里按顺序执行的 shell 命令以官方的 LLM 示例 host/examples/llm.json 为例它先安装python3和py3-pip再用一条 postBuild 命令装好推理框架postBuild: { commands: [ pip3 install --break-system-packages llm llm-anthropic ] }一条命令构建即可得到一个带 LLM 工具的 AI 沙箱gondolin build --config host/examples/llm.json --output ./llm-assets GONDOLIN_GUEST_DIR./llm-assets gondolin exec -- llm --help macOS 上带postBuild.commands的构建会自动走容器执行 chroot 命令原生 Linux 上则需要 root 权限或使用container.forcetrue。更复杂的场景Chromium 沙箱官方的浏览器示例 host/examples/chromium.json 展示了两个进阶用法在rootfsPackages中加入chromium、mesa-dri-gallium、font-noto、xvfb-run等包通过init.rootfsInitExtra指定额外的 init 脚本对应 host/examples/chromium-init-extra.sh在sandboxd启动前完成 Xvfb 等环境准备配合--tag browser-use:latest给镜像打标签后即可被browser-use.ts这类 Agent 脚本通过 ingress 网关驱动——这是AI 在沙箱里操作真实浏览器的完整链路。跨发行版方案用 OCI rootfs 替代 Alpine 用户态不想局限于 AlpineGondolin 支持直接用任意 OCI 镜像Docker Hub / GHCR / 私有仓库作为rootfs 基座。原理见 docs/custom-images.md 的 OCI 一节实现代码在 host/src/alpine/oci.ts┌─────────────────────────────────────────────┐ │ Boot 层仍是 Alpine内核包 内核镜像 initramfs │ ├─────────────────────────────────────────────┤ │ Rootfs 层来自 OCIDebian/Ubuntu 用户态文件系统 │ └─────────────────────────────────────────────┘也就是说OCI 模式只替换根文件系统内容启动工件仍由 Alpine 组件组装。参考官方示例 host/examples/oci-debian.json{ arch: aarch64, distro: alpine, oci: { image: docker.io/library/debian:bookworm-slim, pullPolicy: if-not-present } }执行gondolin build --config host/examples/oci-debian.json --output ./oci-assets后构建器会通过 Docker/Podman 拉取镜像、导出 tar 并保留文件 UID/GID 属主信息最终得到一台内核是 Alpine、用户态是 Debian的混合沙箱。几个实用细节设置oci后alpine.rootfsPackages会被忽略rootfs 内容完全来自 OCI 镜像导出的 rootfs 必须包含/bin/sh否则需要提供自定义init.rootfsInitpullPolicy可选if-not-present默认、always、never三种拉取策略跨架构构建与使用自定义镜像构建机与目标架构不一致时直接加--arch即可缺原生工具时会自动改用容器构建# 在 Apple Silicon 上构建 x86_64 镜像 gondolin build --arch x86_64 --config build-config.json --output ./x64-assets构建产物有三种使用方式环境变量GONDOLIN_GUEST_DIR./my-assets gondolin bashCLI 标签构建时加--tag my-image:latest之后按镜像名引用SDKVM.create({ sandbox: { imagePath: ./my-assets } })指向资产目录完整的 CLI 参数说明见 docs/cli.md。常见问题速查症状解决方案mke2fs: command not found安装e2fsprogsmacOS 上确认其在 PATH 中brew --prefix e2fsprogsOCI 构建缺debugfsDebian/Ubuntu 的e2fsprogs已包含Alpine 宿主持需装e2fsprogs-extra构建超时 / VM 不启动确认架构匹配Apple Silicon 用aarch64x86_64 Linux 用x86_64包找不到Alpine 包分散在main与community仓库两者默认均已启用镜像过大精简rootfsPackages、选用更小的linux-virt内核、固定rootfs.sizeMb总结Gondolin 自定义沙箱镜像的核心思路是配方即代码一份 JSON 配置Alpine 包列表 postBuild 命令 可选 OCI 基座就能生成一套带校验和、可复现、可跨架构的 micro-VM 启动工件。无论是给 AI Agent 装一个推理框架还是造一个带 Chromium 的浏览器沙箱都只需几十行的配置差异。下一步可以阅读 host/src/build/ 下的流水线源码或 docs/architecture.md 了解控制面与沙箱的通信机制。【免费下载链接】gondolinExperimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox项目地址: https://gitcode.com/gh_mirrors/go/gondolin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考