Gondolin – Secure Local Sandbox for AI Agents

What it is A Node‑based SDK and CLI that runs code generated by AI agents inside tiny, disposable Linux micro‑VMs (QEMU by default, optional krun backend). The host controls network and filesystem access through programmable JavaScript policies, letting you inject secrets safely and limit egress to approved hosts.

Why it matters AI agents often produce scripts that need to call external APIs or handle credentials. Running those scripts unchecked on the host is a security risk. Gondolin isolates each agent turn in a fast, lightweight VM and enforces fine‑grained egress rules, reducing the chance of data exfiltration or malicious network activity.

---

Key Features

• Micro‑VM sandbox – Quick‑boot Linux VMs (~200 MB) using QEMU or the experimental krun hypervisor.
• Programmable HTTP/TLS policy – Allow‑list hosts, inject secrets only for permitted destinations, and hook request/response bodies via JavaScript.
• Secret placeholders – The guest sees a dummy token; the real secret is substituted by the host at runtime for allowed calls.
• Custom VFS mounts – Define file‑system behavior (read‑only, copy‑on‑write, in‑memory) from JavaScript.
• Ingress gateway – Expose guest HTTP services on the host (--listen or vm.enableIngress()).
• SSH support – Host‑to‑guest shell access and optional guest‑to‑upstream SSH egress (proxied).
• Snapshots & resume – Pause a VM, snapshot its disk state, and later resume from that point.
• Image pipeline – Alpine‑based rootfs builder, OCI‑compatible images, and custom kernel/initramfs support.
• Cross‑platform – Works on macOS (via Hypervisor.framework) and Linux; ARM64 is the most tested architecture.

---

Typical Use Cases

Scenario	How Gondolin helps
LLM‑driven automation (e.g., code generation, web‑scraping)	Run the generated script in an isolated VM, inject API keys only for whitelisted domains, and capture output safely.
Agent‑based testing (CI for AI‑generated code)	Spin up a fresh VM per test, enforce network policies, and discard the VM after the run to avoid side‑effects.
Secure credential handling	Store secrets on the host, expose them to the guest only when a request matches an allowed host, preventing accidental leakage.
Browser automation inside a sandbox	Launch Chromium inside a VM and expose only the DevTools endpoint to a host‑side agent, keeping the browser isolated from the host OS.
Research on AI agents	Provide a reproducible, auditable environment for each agent turn, with snapshotting for later inspection.

---

Getting Started (CLI)

# Install the package (includes optional runners)
npm i -g @earendil-works/gondolin

# Open an interactive shell in a fresh VM
npx @earendil-works/gondolin bash

# List active sessions
npx @earendil-works/gondolin list

# Attach to a running VM
npx @earendil-works/gondolin attach <session-id>

# Snapshot a VM (stops it)
npx @earendil-works/gondolin snapshot <session-id>

# Resume from a snapshot
npx @earendil-works/gondolin bash --resume <snapshot-id-or-path>

Prerequisites

• macOS: brew install qemu node
• Linux (Debian/Ubuntu): sudo apt install qemu-system-arm nodejs npm
• For the experimental krun backend, follow the make krun-runner instructions (requires Rust, Zig, and several dev libraries).

---

SDK Example (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();

The guest only sees a placeholder token; the real token is injected by the host when the request matches api.github.com.

---

Limitations & Known Issues

• Experimental krun backend – Still considered beta; may lack full feature parity with QEMU.
• Image size – Base images (~200 MB) are cached on first use; large custom images increase startup time.
• Platform support – macOS and Linux only; Windows not currently supported.
• Network policy granularity – Policies are applied per‑host; fine‑grained path‑level controls are not built‑in.
• Resource limits – VM memory and CPU are configurable but not automatically sandboxed beyond what the host OS provides.

---

License & Community

• License: Apache‑2.0
• Documentation: https://earendil-works.github.io/gondolin/
• Issue tracker: https://github.com/earendil-works/gondolin/issues
• Contributions: The repo includes guides for the host package, guest build pipeline, and example integrations (Pi tools, Chromium, Browser‑Use).

---

Gondolin is built with assistance from AI coding agents, but the security‑critical components (policy engine, secret handling, VM isolation) are authored and reviewed by humans.