@deckyard/virtualbox

Oracle VirtualBox 7 for Jennifer programs, through the VBoxManage command line: list machines, disks and networks, create and delete machines, start and stop them, forward ports, take and restore snapshots, clone, import and export appliances, read the guest's IP, and run commands or copy files in the guest. Names and paths are checked before they reach VBoxManage, a guest password never appears on a command line, and a command prefix (ssh) drives a VirtualBox on another machine.

Documentation

Install

jvc add @deckyard/virtualbox

This vendors the deck to vendor/<scope>/virtualbox/. Without jvc, unpack the src/ subtree of a release archive (<scope>-virtualbox-<version>.tar.gz) there.

Usage

use io;

import "@deckyard/virtualbox/" as virtualbox;

def vb as virtualbox.Host init virtualbox.open(virtualbox.local());
virtualbox.importAs($vb, "debian.ova", "build-1");
virtualbox.addForward($vb, "build-1", virtualbox.forward(1, "ssh", 2222, 22));
virtualbox.start($vb, "build-1");
io.printf("up at %s\n", virtualbox.waitForIp($vb, "build-1", 0, 180000));

Requirements

Jennifer 0.26.0 or newer, the default jennifer binary (the deck runs programs, capability exec; jennifer-tiny cannot), and VirtualBox 7.0 or newer with VBoxManage on PATH, here or on the host a prefix reaches. Commands and copies in the guest need the Guest Additions.

Development

tools/check-all.sh                   # the full gate, as CI runs it
jennifer test src/virtualbox_test.j  # the tests, against a fake VBoxManage
tools/check-docs.sh                  # docs against the code
tools/pack.sh dist                   # build the release archive

Licence

LGPL-3.0-only, see LICENSE. Copyright (C) 2026 mplx <[email protected]>.

tools/check-headers.sh checks every source file's SPDX header against deck.toml.