Berry Wiki

Gondolin

Properties2
tagsai, sandboxing
aliasesGondolin

9 min read

Gondolin

Checked: 2026-07-14

Project Summary

Gondolin is a local coding-agent sandbox. It runs untrusted code inside a small Linux virtual machine (VM) while a trusted TypeScript process on the host controls network access, secrets, and visible files.

  • Default VM engine: QEMU
  • Optional engine: Experimental libkrun backend
  • Host package: @earendil-works/gondolin 0.12.0
  • Implementation: TypeScript host control plane and Zig guest services
  • License: Apache-2.0
  • Status: The project calls itself early and experimental

Problem Solved

Coding agents need to execute generated code, install packages, call external services, and modify files. Giving them normal host access exposes credentials, private files, localhost services, and other machines.

Gondolin addresses all three paths:

  • Compute: Put untrusted processes behind a VM boundary.
  • Network: Mediate outbound traffic in host code instead of giving the VM normal network access.
  • Secrets and files: Keep real credentials on the host and expose only explicit, programmable storage.

How It Works

  1. The Node.js host process starts a minimal QEMU VM with a small virtio device set.
  2. A guest daemon receives command requests over a virtio-serial channel.
  3. A guest FUSE filesystem forwards file operations to host-side virtual filesystem providers.
  4. A host-written network stack receives VM Ethernet traffic through QEMU’s stream socket.
  5. The host classifies and mediates HTTP, TLS, optional SSH, and explicitly mapped TCP traffic.
  6. The host can replace secret placeholders in approved HTTP headers immediately before sending a request.
  7. The root disk uses copy-on-write storage. Sessions may use memory-like temporary overlays, persistent overlays, or read-only roots.
  8. Disk-only checkpoints can stop and later resume a session’s disk state.

The CLI can start a shell, execute commands, list and attach to sessions, create snapshots, resume them, expose a guest HTTP service, and enable SSH. The TypeScript software development kit provides lower-level policy hooks.

Security Boundary

  • Compute boundary: QEMU by default, with -nodefaults and a limited virtio device set. The guest does not directly share the host kernel.
  • Policy boundary: The trusted host Node.js process owns network rules, real secrets, and filesystem providers. The guest is treated as hostile.
  • Default network shape: No raw network address translation. Unknown TCP protocols are denied, non-DNS UDP is blocked, and HTTP CONNECT is denied.
  • Filesystem shape: The guest sees its image, temporary filesystems, and optional host-controlled mounts. Host files are unavailable unless a provider exposes them.

The official threat model does not defend against a malicious host, another attacker with the same host account, VM escape, side channels, or denial of service. The QEMU boundary is fundamental: a QEMU escape is a host compromise.

Platforms And Agents

  • Hosts: macOS and Linux. Windows is not supported.
  • Architectures: ARM64 is the most tested path. QEMU supports matching AArch64 or x86-64 guest assets; libkrun requires guest and host architectures to match.
  • Guest image: Alpine Linux. The image builder currently supports Alpine only.
  • Runtime: Node.js 23.6 or newer for the published host package.
  • Agents: Designed for coding agents in general. The repository provides a Pi + Gondolin extension that sends Pi tool execution into the VM and mounts the project at /workspace.
  • Claude Code and Codex: No first-party integration was found. They could run inside a suitable custom image, but that workflow is not documented as turnkey.

Setup And Workflow

For the default path:

  1. Install Node.js and QEMU.
  2. Run the Gondolin package through npx or install it in an application.
  3. On first use, let Gondolin download and cache roughly 200 MB or more of guest assets. The default image is alpine-base:latest.
  4. Start a shell or create a VM through the TypeScript API.
  5. Configure exact network hosts, secrets, filesystem providers, and persistence mode.
  6. Close the VM or checkpoint its disk state.

Extra compilers, language runtimes, and tools require building a custom Alpine image. The optional libkrun backend needs an additional runner and compatible boot assets; official guidance recommends QEMU unless libkrun testing is the goal.

Network And Credentials

Network

  • HTTP/TLS: Host-mediated. The host parses plain HTTP and intercepts TLS, then replays allowed requests with fetch.
  • Host rules: Exact hosts and wildcard patterns are supported. Internal, loopback, link-local, private, carrier-grade NAT, and metadata-style ranges are blocked by default.
  • Redirects: Each destination is checked again.
  • DNS: Synthetic mode is the default and prevents DNS from becoming a general egress channel. Trusted and open modes relax this.
  • SSH: Optional, allowlisted, proxied, host-key-verified, and aimed at command execution rather than an unrestricted tunnel.
  • Mapped TCP: Optional explicit host/port mappings. These are raw transport exceptions and bypass HTTP content hooks and secret substitution.
  • Ingress: The host may expose a guest HTTP service through a controlled gateway.

Gondolin supports HTTP/1.x and intercepted HTTPS. It does not currently support HTTP/2, HTTP/3, QUIC, WebRTC, generic UDP, or arbitrary TCP protocols unless an explicit mapping is added.

Credentials

The preferred secret flow never places a real secret inside the guest:

  1. The guest receives a random placeholder in an environment variable.
  2. The guest builds an HTTP header using that placeholder.
  3. The host replaces it with the real secret only when the destination matches that secret’s allowlist.
  4. A placeholder sent toward a disallowed host causes the request to be blocked.

Header substitution includes normal authorization headers and Basic authentication. Query-string replacement is opt-in. Request bodies, paths, and responses are not substituted.

Important limits:

  • An allowed service can still receive any guest-readable data.
  • A service that echoes request headers can reveal a substituted secret back to the guest.
  • Custom request/response hooks may see real secrets after substitution and can accidentally log them.
  • Raw mapped TCP and SSH do not use HTTP secret substitution.
  • Putting real secrets directly in the guest environment or mounting credential files defeats the intended protection.

Strengths

  • Purpose-built for hostile agent code: The threat model directly covers prompt-injected and generated code.
  • Real VM isolation: Stronger compute boundary than a shared-kernel container.
  • Host-side policy: The guest cannot simply disable the egress or filesystem controls.
  • Secret non-exposure: Placeholder substitution is more protective than copying API tokens into a VM.
  • Content-aware HTTP: Policy hooks can inspect methods, paths, headers, bodies, responses, redirects, resolved addresses, and destination hosts.
  • DNS rebinding defenses: Policy is checked before the request and again when connecting.
  • Programmable filesystem: In-memory, real host, read-only, routing, and custom JavaScript providers are available.
  • Fast local start: Official documentation reports sub-second micro-VM boot.
  • Disk checkpoints: Copy-on-write snapshots support resumable disk state.
  • macOS and Linux: Broader laptop support than Linux/KVM-only tools.

Limits And Risks

  • Early maturity: The project explicitly asks evaluators to treat its limitations as a production-readiness checklist.
  • Alpine-only builder: Other guest distributions are not currently built by the official pipeline.
  • Custom image work: Adding common development runtimes or packages requires building a new image.
  • Narrow protocols: No HTTP/2, HTTP/3, QUIC, WebRTC, broad UDP, or general raw networking.
  • No memory snapshots: Checkpoints save disk state, not running processes or RAM. Several guest paths are temporary and absent from checkpoints.
  • Allowed-host exfiltration: Network policy limits destinations, not what data can be uploaded to an approved destination.
  • TLS interception: A local certificate authority is created and trusted by the guest. Its private key is sensitive, and some clients may reject interception or certificate pinning.
  • Mapped exceptions weaken policy: Raw TCP mappings bypass HTTP inspection and secret controls.
  • No complete resource control: A guest can consume CPU, memory, or host work. Buffer limits are not full denial-of-service protection.
  • Same-user host attacker: Temporary sockets and cached files can be interfered with by another process under the same host account.
  • VM escape remains: Security ultimately relies on QEMU or libkrun.
  • Backend gaps: Libkrun is experimental and has incomplete parity and networking edge cases.
  • No Windows host: Windows users need another system.

Activity And Maturity

  • Repository created: 2026-02-03
  • Latest push when checked: 2026-07-06
  • Repository signal: 405 commits displayed, about 1,691 stars, 105 forks, and 33 combined open issues and pull requests in GitHub metadata
  • Package version: 0.12.0
  • Releases: GitHub displayed 26 releases; the latest visible entry was a 0.12.0 sandbox-helper release dated 2026-05-19.
  • Assessment: Fast-moving and unusually well documented for its age, with a detailed threat model and tests. It is still a pre-1.0 experimental project with important protocol, image, snapshot, and resource-control gaps. Test it against the intended agent and services before production use.

Best Fit

Gondolin best fits developers who:

  • run local coding agents on macOS or Linux;
  • need stronger isolation than containers;
  • must let an agent call a small set of HTTP APIs without revealing tokens;
  • want JavaScript control over network requests and filesystem behavior;
  • can use Alpine or maintain a custom image;
  • can accept restricted protocols.

It is a weak fit for workloads requiring general internet access, HTTP/2-only APIs, UDP, VPNs, arbitrary developer tools without image-building, Windows hosts, full live VM restore, or hardened multi-tenant resource control.

Comparison-Relevant Facts

FactGondolin
Primary purposeLocal agent sandbox
Compute boundaryQEMU micro-VM; experimental libkrun option
Host supportmacOS and Linux
GuestMinimal Alpine Linux
Agent integrationPi extension; generic CLI and TypeScript API
Default networkHost-mediated HTTP/TLS, synthetic DNS, other traffic denied
Destination controlHostname allowlists plus resolved-IP checks
Internal network protectionBlocked by default
Secret handlingGuest placeholders; host substitution for approved HTTP hosts
Arbitrary TCP/UDPNo; explicit TCP mappings and limited DNS/SSH exceptions
Source/filesProgrammable host-side virtual filesystem providers
PersistenceRead-only, temporary, or copy-on-write root; disk checkpoints
IngressControlled host-to-guest HTTP gateway
Root requirementNormal QEMU path is documented without a standing root service; host prerequisites still apply
ConfigurationCLI plus TypeScript policy hooks
LicenseApache-2.0

Hacker News Context

In the Clawk thread, one commenter proposed a separate machine using QEMU/KVM, a credential-hiding proxy, disposable images, SSH control, and optionally VNC. Another replied that Gondolin matched the description and sends a Pi coding agent’s shell work into a small QEMU VM.

A follow-up questioned whether Gondolin is local while the proposal described a separate machine. The official documentation resolves this: Gondolin is a local macOS/Linux sandbox. It does not provide a remote-machine control plane. It matches the VM, controlled-network, hidden-secret, and disposable-image ideas, but not the separate-host part.

The HN statement that it sends “all of the agent’s bash” into the VM applies specifically to the Pi integration. Gondolin itself is a general CLI and TypeScript library, not a universal interception layer for every agent.

Unknowns

  • Independent audit: No completed external security audit was found in the reviewed official material.
  • Production users: Official evidence of production-scale deployments was not found.
  • Performance: The sub-second boot claim was not independently benchmarked here.
  • Claude Code/Codex flow: No official first-party integration or tested compatibility guide was found.
  • Release meaning: GitHub’s latest visible release title refers to sandbox helpers; exact release coordination across the core package, helpers, and images was not fully established.

Sources

Graph View