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駆動の自動化（例：コード生成、Webスクレイピング）	生成されたスクリプトを分離された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