vbox

package
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 24, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package vbox wraps the VBoxManage CLI. Every VirtualBox interaction in the server flows through Client.Run so that error formatting, dry-run handling, debug logging and CRLF normalisation happen in exactly one place.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatError

func FormatError(err error) string

FormatError renders any error for return to the MCP caller. VBoxErrors are prefixed with their code; other errors return their message. Raw VBoxManage stderr never leaks unformatted.

func ParseMachineReadable

func ParseMachineReadable(output string) map[string]string

ParseMachineReadable parses `--machinereadable` output (key="value" lines) into a map. Surrounding quotes are stripped and escaped backslashes ("\\") are unescaped, matching VBoxManage's Windows path encoding.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client executes VBoxManage commands using a shared Config.

func New

func New(cfg *Config) *Client

New returns a Client bound to cfg.

func (*Client) Config

func (c *Client) Config() *Config

Config exposes the underlying configuration (path, screenshot dir, etc.).

func (*Client) Run

func (c *Client) Run(ctx context.Context, args ...string) (string, error)

Run invokes VBoxManage with args and returns normalised stdout. It never uses a shell, so arguments are passed verbatim with no injection risk. On failure it returns a *VBoxError carrying the parsed VBOX_E_* code.

type Config

type Config struct {
	// VBoxManagePath is the path to the VBoxManage executable.
	VBoxManagePath string
	// ScreenshotDir is where transient screenshot PNGs are written before being
	// read back and returned to the caller.
	ScreenshotDir string
	// DefaultTimeout bounds helper operations (e.g. the mouse web-service call).
	DefaultTimeout time.Duration
	// DryRun, when true, logs VBoxManage commands instead of executing them.
	DryRun bool
	// Debug, when true, logs every VBoxManage invocation to stderr.
	Debug bool
	// ReadOnly, when true, disables every tool that can modify a VM or its
	// guest (create/delete/modify/start/stop/input/exec/...), leaving only
	// observation tools. A safety valve for pointing an agent at real VMs.
	ReadOnly bool
}

Config holds runtime configuration for the VirtualBox MCP server. Values are resolved from environment variables with sensible cross-platform defaults.

func Load

func Load() *Config

Load builds a Config from the environment, matching the behaviour of the upstream TypeScript server (VBOXMANAGE_PATH, SCREENSHOT_DIR, DEFAULT_TIMEOUT, VBOXMANAGE_DRY_RUN, VBOXMANAGE_DEBUG).

func (*Config) Logf

func (c *Config) Logf(format string, args ...any)

Logf writes a debug line to stderr when Debug is enabled. stderr is used because stdout carries the MCP protocol.

type VBoxError

type VBoxError struct {
	// Code is the parsed VBOX_E_* code, or "UNKNOWN".
	Code string
	// Command is the VBoxManage subcommand that failed (e.g. "startvm").
	Command string
	// Message is the human-readable error, including VBoxManage stderr.
	Message string
}

VBoxError represents a failed VBoxManage invocation.

func (*VBoxError) Error

func (e *VBoxError) Error() string

type VM

type VM struct {
	Name string `json:"name"`
	UUID string `json:"uuid"`
}

VM is a name/UUID pair as reported by `VBoxManage list vms`.

func ParseVMList

func ParseVMList(output string) []VM

ParseVMList parses `"name" {uuid}` lines from `VBoxManage list vms`.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL