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

Gondolin – AI 에이전트를 위한 안전한 로컬 샌드박스

개요 AI 에이전트가 생성한 코드를 작고 일회용인 Linux 마이크로 VM(QEMU 기본, 선택적 krun 백엔드)에서 실행하는 Node 기반 SDK 및 CLI입니다. 호스트는 프로그래밍 가능한 JavaScript 정책을 통해 네트워크 및 파일 시스템 액세스를 제어하여 비밀을 안전하게 주입하고 승인된 호스트로만 이그레스를 제한할 수 있습니다.

중요성 AI 에이전트는 종종 외부 API를 호출하거나 자격 증명을 처리해야 하는 스크립트를 생성합니다. 호스트에서 이러한 스크립트를 검사 없이 실행하는 것은 보안 위험입니다. Gondolin은 각 에이전트 턴을 빠르고 가벼운 VM에서 격리하고 세분화된 이그레스 규칙을 적용하여 데이터 유출이나 악의적인 네트워크 활동의 가능성을 줄입니다.

주요 기능

마이크로 VM 샌드박스 – QEMU 또는 실험적인 krun 하이퍼바이저를 사용하는 빠른 부팅 Linux VM(약 200MB).
프로그래밍 가능한 HTTP/TLS 정책 – 호스트를 허용 목록에 추가하고, 허용된 대상에만 비밀을 주입하며, JavaScript를 통해 요청/응답 본문을 후킹합니다.
비밀 자리 표시자 – 게스트는 더미 토큰을 볼 수 있으며, 실제 비밀은 허용된 호출에 대해 런타임에 호스트가 대체합니다.
사용자 정의 VFS 마운트 – JavaScript에서 파일 시스템 동작(읽기 전용, 복사-온-쓰기, 메모리 내)을 정의합니다.
수신 게이트웨이 – 호스트에서 게스트 HTTP 서비스를 노출합니다(--listen 또는 vm.enableIngress()).
SSH 지원 – 호스트-게스트 셸 액세스 및 선택적 게스트-업스트림 SSH 이그레스(프록시).
스냅샷 및 재개 – VM을 일시 중지하고, 디스크 상태를 스냅샷하고, 나중에 해당 지점에서 재개합니다.
이미지 파이프라인 – Alpine 기반 rootfs 빌더, OCI 호환 이미지, 사용자 정의 커널/initramfs 지원.
크로스 플랫폼 – macOS(Hypervisor.framework 통해) 및 Linux에서 작동하며, ARM64가 가장 많이 테스트된 아키텍처입니다.

일반적인 사용 사례

시나리오	Gondolin이 도움이 되는 방법
LLM 기반 자동화 (예: 코드 생성, 웹 스크래핑)	생성된 스크립트를 격리된 VM에서 실행하고, 허용된 도메인에만 API 키를 주입하며, 출력을 안전하게 캡처합니다.
에이전트 기반 테스트 (AI 생성 코드용 CI)	테스트마다 새 VM을 시작하고, 네트워크 정책을 적용하며, 실행 후 VM을 폐기하여 부작용을 방지합니다.
안전한 자격 증명 처리	호스트에 비밀을 저장하고, 요청이 허용된 호스트와 일치할 때만 게스트에 노출하여 우발적 유출을 방지합니다.
샌드박스 내 브라우저 자동화	VM 내에서 Chromium을 실행하고 DevTools 엔드포인트만 호스트 측 에이전트에 노출하여 브라우저를 호스트 OS와 격리합니다.
AI 에이전트 연구	각 에이전트 턴에 대해 재현 가능하고 감사 가능한 환경을 제공하고, 나중에 검사할 수 있도록 스냅샷을 제공합니다.

시작하기 (CLI)

# 패키지 설치 (선택적 러너 포함)
npm i -g @earendil-works/gondolin

# 새 VM에서 대화형 셸 열기
npx @earendil-works/gondolin bash

# 활성 세션 목록
npx @earendil-works/gondolin list

# 실행 중인 VM에 연결
npx @earendil-works/gondolin attach <session-id>

# VM 스냅샷 (중지)
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와 완전한 기능 동등성이 부족할 수 있습니다.
이미지 크기 – 기본 이미지(약 200MB)는 첫 사용 시 캐시되며, 큰 사용자 정의 이미지는 시작 시간을 증가시킵니다.
플랫폼 지원 – macOS 및 Linux만 지원하며 Windows는 현재 지원되지 않습니다.
네트워크 정책 세분성 – 정책은 호스트별로 적용되며, 세분화된 경로 수준 제어는 내장되어 있지 않습니다.
리소스 제한 – VM 메모리 및 CPU는 구성 가능하지만 호스트 OS가 제공하는 것 이상으로 자동 샌드박싱되지는 않습니다.

라이선스 및 커뮤니티

라이선스: Apache-2.0
문서: https://earendil-works.github.io/gondolin/
이슈 트래커: https://github.com/earendil-works/gondolin/issues
기여: 저장소에는 호스트 패키지, 게스트 빌드 파이프라인 및 예제 통합(Pi 도구, Chromium, Browser-Use)에 대한 가이드가 포함되어 있습니다.

Gondolin은 AI 코딩 에이전트의 도움으로 구축되었지만, 보안에 중요한 구성 요소(정책 엔진, 비밀 처리, VM 격리)는 인간이 작성하고 검토했습니다.

earendil-works/gondolin