@edgible-team/sdk
    Preparing search index...

    Class VirtualMachine

    VM lifecycle helpers (R5) — QEMU-backed VM orchestration ported from integration_tests/lib/vm/**. Node-only: exposed via @edgible-team/sdk/node (documented deviation from architecture.md "tier 3 in root" — the root build must stay browser-safe, and this code is fs/child_process-heavy).

    Index

    Constructors

    constructor

    Methods

    exec execWithStdin getGuestPath getOverlayPath getSshPort getSshUser start stop syncCode waitForSsh

    Constructors

    Methods

    • Run a command in the guest over SSH. Never rejects; check exitCode.

      Parameters

      • command: string
      • Optionaloptions: { timeout?: number }

      Returns Promise<ExecResult>

    • Run a script passed via stdin (avoids command-line length limits).

      Parameters

      • script: string
      • Optionaloptions: { timeout?: number }

      Returns Promise<ExecResult>

    • Path to the CoW overlay this VM booted from ('' before start()). With keepOverlay: true the overlay survives stop(), so a caller can capture this path and adopt the overlay as a persistent disk.

      Returns string

    • Boot the VM: create a qcow2 overlay beside the base image (a CoW copy when resuming a loadvmTag snapshot), allocate a host SSH port from sshPortRange (default 2222–2299), spawn QEMU, and wait for SSH. Warm boots also re-sync the guest wall clock from the host.

      Host mutation: spawns a long-lived QEMU process (registered with the process-exit safety net described in the module header) and writes the overlay image into <imageDir>/overlays/.

      Throws a plain Error when the base image is missing, the overlay/copy cannot be created, no port in the range is free, or SSH never becomes ready (in which case the VM is stopped first).

      Returns Promise<void>

      const vm = new VirtualMachine({ baseImagePath: '/path/to/images/base.qcow2' });
      await vm.start();
      try {
        const { exitCode, stdout } = await vm.exec('uname -a');
      } finally {
        await vm.stop();
      }

    • Graceful guest shutdown → SIGKILL fallback → overlay unlink → port release. Idempotent.

      Returns Promise<void>

    • Poll until the guest answers over SSH: 30 attempts at 2s intervals for a cold boot, 6 attempts at 1s for a warm (snapshot) boot. On exhaustion the VM is stopped and a plain Error is thrown. Called by start(); exposed for callers that restart sshd in the guest.

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods