Experimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox

Gondolin – 面向AI代理的安全本地沙箱

它是什么 一个基于Node的SDK和CLI，用于在微型、一次性的Linux微虚拟机（默认使用QEMU，可选krun后端）中运行AI代理生成的代码。主机通过可编程的JavaScript策略控制网络和文件系统访问，让您安全地注入机密，并将出口限制为已批准的主机。

为什么重要 AI代理经常生成需要调用外部API或处理凭据的脚本。在主机上不加检查地运行这些脚本存在安全风险。Gondolin将每个代理回合隔离在快速、轻量级的虚拟机中，并强制执行细粒度的出口规则，从而降低数据泄露或恶意网络活动的可能性。

主要特性

微虚拟机沙箱 – 使用QEMU或实验性的krun虚拟机监控程序快速启动Linux虚拟机（约200 MB）。
可编程HTTP/TLS策略 – 允许列表主机，仅对允许的目标注入机密，并通过JavaScript挂钩请求/响应体。
机密占位符 – 客户机看到虚拟令牌；主机在运行时为允许的调用替换真实机密。
自定义VFS挂载 – 通过JavaScript定义文件系统行为（只读、写时复制、内存中）。
入口网关 – 在主机上暴露客户机HTTP服务（--listen或vm.enableIngress()）。
SSH支持 – 主机到客户机的shell访问，以及可选的客户机到上游的SSH出口（代理）。
快照与恢复 – 暂停虚拟机，快照其磁盘状态，稍后从该点恢复。
镜像流水线 – 基于Alpine的根文件系统构建器、OCI兼容镜像，以及自定义内核/initramfs支持。
跨平台 – 在macOS（通过Hypervisor.framework）和Linux上运行；ARM64是测试最多的架构。

典型使用场景

场景	Gondolin如何帮助
LLM驱动的自动化（例如，代码生成、网页抓取）	在隔离的虚拟机中运行生成的脚本，仅对白名单域注入API密钥，并安全捕获输出。
基于代理的测试（AI生成代码的CI）	每次测试启动一个新的虚拟机，强制执行网络策略，运行后丢弃虚拟机以避免副作用。
安全凭据处理	在主机上存储机密，仅当请求匹配允许的主机时将其暴露给客户机，防止意外泄漏。
沙箱内的浏览器自动化	在虚拟机内启动Chromium，仅将DevTools端点暴露给主机端代理，使浏览器与主机操作系统隔离。
AI代理研究	为每个代理回合提供可重现、可审计的环境，并支持快照以供后续检查。

快速入门（CLI）

# 安装包（包括可选运行器）
npm i -g @earendil-works/gondolin

# 在新虚拟机中打开交互式shell
npx @earendil-works/gondolin bash

# 列出活动会话
npx @earendil-works/gondolin list

# 附加到正在运行的虚拟机
npx @earendil-works/gondolin attach <session-id>

# 快照虚拟机（停止它）
npx @earendil-works/gondolin snapshot <session-id>

# 从快照恢复
npx @earendil-works/gondolin bash --resume <snapshot-id-or-path>

先决条件

macOS：brew install qemu node
Linux（Debian/Ubuntu）：sudo apt install qemu-system-arm nodejs npm
对于实验性的krun后端，请遵循make krun-runner说明（需要Rust、Zig和多个开发库）。

SDK示例（TypeScript）

import { VM, createHttpHooks } from "@earendil-works/gondolin";

const { httpHooks, env } = createHttpHooks({
  allowedHosts: ["api.github.com"],
  secrets: {
    GITHUB_TOKEN: {
      hosts: ["api.github.com"],
      value: process.env.GITHUB_TOKEN,
    },
  },
});

const vm = await VM.create({ httpHooks, env });

const result = await vm.exec(`
  curl -sS -f \
    -H "Accept: application/vnd.github+json" \
    -H "Authorization: Bearer $GITHUB_TOKEN" \
    https://api.github.com/user
`);

console.log("exitCode:", result.exitCode);
console.log("stdout:\n", result.stdout);
console.log("stderr:\n", result.stderr);

await vm.close();

客户机只看到占位符令牌；当请求匹配api.github.com时，主机注入真实令牌。

限制与已知问题

实验性的krun后端 – 仍被视为测试版；可能与QEMU功能不完全一致。
镜像大小 – 基础镜像（约200 MB）在首次使用时缓存；大型自定义镜像会增加启动时间。
平台支持 – 仅支持macOS和Linux；目前不支持Windows。
网络策略粒度 – 策略按主机应用；未内置细粒度的路径级控制。
资源限制 – 虚拟机内存和CPU可配置，但不会自动超出主机操作系统提供的沙箱限制。

许可证与社区

许可证： Apache-2.0
文档： https://earendil-works.github.io/gondolin/
问题跟踪器： https://github.com/earendil-works/gondolin/issues
贡献： 仓库包含主机包、客户机构建流水线和示例集成（Pi工具、Chromium、Browser-Use）的指南。

Gondolin是在AI编码代理的帮助下构建的，但安全关键组件（策略引擎、机密处理、虚拟机隔离）由人工编写和审查。

earendil-works/gondolin