@deckyard/virtualboxws

Oracle VirtualBox 7 for Jennifer programs, through VirtualBox's SOAP web service (vboxwebsrv): list machines, start and stop them, take and restore snapshots, clone, import and export appliances, and read the guest's IP, on a host reached over HTTP(S) instead of by running VBoxManage (that is the @deckyard/virtualbox deck). Every object reference is released, long operations have deadlines, and the password is not sent over plain http to another machine unless asked.

Documentation

Install

jvc add @deckyard/virtualboxws

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

Usage

use io;
use os;

import "@deckyard/virtualboxws/" as virtualboxws;

def s as virtualboxws.Session init virtualboxws.logon(
    virtualboxws.endpoint("https://vmhost:18083/"), "admin", os.getEnv("VBOX_PASSWORD"));
virtualboxws.start($s, "web");
io.printf("up at %s\n", virtualboxws.waitForIp($s, "web", 0, 180000));
virtualboxws.logoff($s);

Requirements

Jennifer 0.26.0 or newer, the default jennifer binary (the deck needs net; the stock jennifer-tiny has no network driver), and VirtualBox 7.0 or newer with its web service, vboxwebsrv, running on the host.

Development

tools/check-all.sh                   # the full gate, as CI runs it
jennifer test src/virtualboxws_test.j  # the tests, against a fake web service
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.