EarendilEarendilGondolinDocumentation
Source

Gondolin Documentation

AI agents are generating code that runs immediately and increasingly without human review. That code often calls external APIs, which means it needs credentials and network access. Sandboxing the compute isn't enough as you need to control network egress and protect secrets from exfiltration. You also want to be able to tightly control the file system, for convenience of the agent and to control persistence.

Gondolin gives you that. Lightweight micro-VMs (libkrun where available, QEMU otherwise) boot in under a second on your Mac or Linux machine. The network stack and virtual filesystem run on the host, in a small daemon, and are programmable from JavaScript, giving you complete control over what the sandbox can access and what secrets it can use.

This documentation helps you get started with it. We also welcome your feedback as this is an early project and we are eager to learn more about how you want to use it.

A little appetizer:

npx @earendil-works/gondolin bash

Or programmatically:

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 });

// NOTE:
// - `vm.exec("...")` runs via `/bin/sh -lc "..."` (shell features work)
// - `vm.exec([cmd, ...argv])` executes `cmd` directly (no shell); a bare name
//   is looked up in the guest's `$PATH`
const cmd = `
  curl -sS -f \
    -H "Accept: application/vnd.github+json" \
    -H "Authorization: Bearer $GITHUB_TOKEN" \
    https://api.github.com/user
`;

// You can pass a string to `vm.exec(...)` as shorthand for `/bin/sh -lc "..."`.
const result = await vm.exec(cmd);

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

await vm.close();

Where to Start

Guides

Reference

  • CLI: every command and option
  • SDK: VMOptions, the VM API and the other exports
  • Environment Variables: every variable Gondolin reads
  • VM Backends: krun and QEMU, how the default is chosen, feature parity

Design & Internals