SDK Reference

This page lists the programmatic API of @earendil-works/gondolin: every VM option, the members of a VM and the other exports. The guides explain how to use them; each entry links to the relevant one.

npm install @earendil-works/gondolin

import { VM } from "@earendil-works/gondolin";

const vm = await VM.create({ memory: "2G" });
const result = await vm.exec("uname -a");
console.log(result.stdout);
await vm.close();

The package is ESM and requires Node.js; VMs are run by the Gondolin daemon (gondolind) from the platform package installed alongside it. See Installation for requirements.

VMOptions

Options of VM.create(options) (and new VM(options)). All fields are optional.

memory, cpus, tmpfs, httpHooks, dns, tcp, ssh, maxHttpBodyBytes, maxHttpResponseBodyBytes and allowWebSockets also exist under sandbox; when both are set, the sandbox value wins.

VmVfsOptions:

Even without vfs, Gondolin mounts /etc/gondolin (ingress routing) and the MITM CA certificate into the guest. vfs: null removes both, so ingress is unavailable and the guest does not get the CA injected for HTTPS interception.

VmRootfsOptions:

Sandbox Options

VMOptions.sandbox (SandboxServerOptions) holds image selection, backend selection and low-level VM settings. Options marked qemu only apply to the QEMU backend: setting one makes the default backend selection pick QEMU, and combining one with vmm: "krun" throws. Options marked local are rejected when the daemon runs on a remote machine.

Daemon Connection Options

VMOptions.native (NativeEngineOptions) tells Gondolin how to reach the daemon. By default it starts the local gondolind binary; see Remote Machines for running VMs elsewhere.

VM

Option types: ShellOptions (command, env, cwd, signal, attach), EnableSshOptions (user, listenHost, listenPort), EnableIngressOptions (listenHost, listenPort, allowWebSockets, hooks, bufferResponseBody, maxBufferedResponseBodyBytes, upstreamHeaderTimeoutMs, upstreamResponseTimeoutMs).

ExecProcess and ExecResult

vm.exec() returns an ExecProcess; awaiting it yields an ExecResult. Options (ExecOptions) are listed in Running Commands.

ExecResult: exitCode, signal, ok, stdout, stderr, stdoutBuffer, stderrBuffer, json(), lines(), id; see What Is in ExecResult.

vm.fs

VmFs operates on paths of the running guest (booting it on first use): access(), mkdir(), listDir(), stat(), rename(), readFile(), readFileStream(), writeFile() and deleteFile(). See Files and Mounts for semantics and examples.

VmCheckpoint

A disk checkpoint (a .qcow2 file with a JSON metadata trailer); see Persistence and Snapshots.

Other Exports

VFS Providers

See Files and Mounts.

• MemoryProvider: in-memory filesystem
• RealFSProvider: a host directory
• ReadonlyProvider: wraps a provider and rejects writes with EROFS
• ShadowProvider, createShadowPathPredicate(): hide paths of a wrapped provider (deny or redirect writes)
• ReadonlyVirtualProvider: base class for read-only, sync-first custom providers
• VirtualProvider, VirtualProviderClass: provider base classes for custom providers
• VirtualFileSystem: mount-routing file system over providers
• SandboxVfsProvider: wrapper that applies VfsHooks to a provider
• Helpers for custom providers: ERRNO, isWriteFlag(), normalizeVfsPath(), VirtualDirent, createVirtualDirStats(), formatVirtualEntries()
• DEFAULT_GUEST_TMPFS: the built-in tmpfs set, for extending tmpfs

Daemon-Served Mounts

Mounts the Gondolin daemon serves itself (also on remote machines); see Files and Mounts.

• nativeMounts.memory(): an in-memory filesystem kept in the daemon
• nativeMounts.host(dir, { readonly, hide, hideWriteMode }): a directory on the daemon's machine
• createObjectMount(provider, options) / nativeMounts.object(...): mount an ObjectProvider (whole-file get/put store) cached by the daemon; ObjectVirtualProvider is its host-side VirtualProvider view

HTTP Hooks and Secrets

See HTTP Hooks and Policies and Secrets.

• createHttpHooks(options): build httpHooks from an allowlist, secrets and callbacks; returns { httpHooks, env, allowedHosts, secretManager }
• createDjsHooks(sourceOrOptions): a JavaScript / TypeScript policy run inside the daemon (tier-2 hooks)
• djsHooksOptionsFromFile(file): load a tier-2 policy file into DjsHooksOptions
• makePlaceholderFunc(options): custom secret placeholder generator; alphabets HEX_ALPHABET, LOWERCASE_ALPHABET, UPPERCASE_ALPHABET, BASE32_ALPHABET, BASE32_HEX_ALPHABET, BASE62_ALPHABET, BASE64URL_ALPHABET
• HttpRequestBlockedError: throw from a hook to block a request
• suggestHostsForSecret(options): suggest upstream hosts for a secret value (what --host-secret NAME without hosts uses)

Network and SSH

See Network Access and SSH.

• Types: DnsOptions, DnsMode, SyntheticDnsHostMappingMode, TcpOptions, HttpHooks, HttpIpAllowInfo, SshOptions, SshCredential, SshExecRequest, SshExecDecision, SshExecPolicy
• getInfoFromSshExecRequest(request): parse a git-over-SSH exec request (service and repository) for SSH exec policies

Ingress

See Ingress.

• IngressGateway, GondolinListeners: the gateway behind vm.enableIngress() and the routing table it reads
• parseListenersFile(), serializeListenersFile(): the /etc/gondolin/listeners format
• IngressRequestBlockedError: throw from an ingress hook to reject a request
• Types: IngressRoute, EnableIngressOptions, IngressAccess, IngressGatewayHooks and the hook request/response types

Sessions

The session registry behind gondolin list / attach; see Running Commands.

• listSessions(): registered sessions with liveness
• findSession(query): a session by UUID or unique prefix
• gcSessions(): remove stale entries and orphan sockets
• connectToSession(socketPath, callbacks): connect to a session's IPC socket
• registerSession(), unregisterSession(), SessionIpcServer: what a VM uses to register itself

Guest Assets and Images

See Images.

• ensureGuestAssets(): download the default image if needed and return its GuestAssets paths
• hasGuestAssets(), getAssetDirectory(), getAssetVersion(): check the default image without downloading
• loadGuestAssets(dir), loadAssetManifest(dir): read an asset directory
• resolveImageSelector(selector), ensureImageSelector(selector): resolve a path, name:tag or build id locally, or also pull it from the registry
• listImageRefs(), setImageRef(), tagImage(), removeImage(), importImageFromDirectory(): manage the local image store
• getImageStoreDirectory(), getImageObjectDirectory(buildId): store paths

Daemon Binaries

For deploying gondolind to other machines; see Remote Machines.

• ensureNativeBinary({ platform, arch }): the multi-call gondolin binary for a platform, downloaded from npm if needed; returns { path, args }
• getNativeBinaryPath(target): the same without downloading, or null
• nativeDaemonCommand(binary), nativeDaemonArgs(binary): the command line that starts the daemon from a binary
• nativePackageName(target), nativeRustTarget(target): npm package and Rust target of a platform
• spawnNativeConnection(command): spawn a daemon command as a NativeConnection for native.connect

Image Build API

See Building Custom Images.

• buildAssets(config, options): build guest assets from a BuildConfig
• verifyAssets(dir): verify asset checksums against the manifest
• getDefaultBuildConfig(), getDefaultArch(), validateBuildConfig(), parseBuildConfig(), serializeBuildConfig(): build configuration helpers
• Types: BuildConfig, AlpineConfig, NixOSConfig, ContainerConfig, OciRootfsConfig, RootfsConfig, InitConfig, RuntimeDefaultsConfig, RootfsMode, Architecture, Distro, ContainerRuntime, OciPullPolicy

Debugging

Types DebugFlag, DebugConfig, DebugComponent and DebugLogFn; see Debugging and Troubleshooting.

Environment Variables

Several defaults above come from environment variables (GONDOLIN_VMM, GONDOLIN_GUEST_DIR, GONDOLIN_DEBUG, GONDOLIN_START_TIMEOUT_MS, GONDOLIN_NATIVE_COMMAND, ...). See Environment Variables for the full list.