winkit

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Overview

Package winkit is the winkit engine: Windows guests built and booted by go-winkit (vz on macOS hosts, qemu on Linux hosts). It runs two guests, chosen by engine.Cell.Guest:

  • engine.WindowsPE: a WinPE boot volume with a WSL1 nix distro (winkit stage pe-wsl). The default.
  • engine.WindowsFull: a full Windows install with a WSL1 nix distro (winkit stage full-wsl).

Both import the distro as "winkit" and run the agent in it with `wsl -d winkit`. They differ in the build stage, the template directory, and the SSH channel the agent command runs over (see guest).

Index

Constants

View Source 
const WindowsISODownloadURL = "https://www.microsoft.com/en-us/software-download/windows11arm64"

WindowsISODownloadURL is the Microsoft page for downloading Windows 11 ARM64 ISO. Kept for the manual-download fallback message in ResolveWindowsISO.

Variables

This section is empty.

Functions

func CacheDir 

func CacheDir(home string) string

CacheDir returns the QEMU media cache directory.

DEVCELL_WINKIT_CACHE_DIR points it somewhere shared. Inside a cell $HOME is itself a per-cell directory, so the default renders as ~/.devcell/<cell>/.devcell/cache/qemu and every cell re-downloads the same ~6 GB of immutable media. There is no way to reach the real host home from inside the container, so the location has to be pointable rather than inferred (CELL-386).

func DownloadVirtioDrivers 

func DownloadVirtioDrivers(ctx context.Context, home string, noCache bool, obs Observer) (string, error)

DownloadVirtioDrivers returns the cached VirtIO drivers ISO at VirtioISOPath, downloading it via winkit when missing or unusable. noCache discards the cached ISO first to force a fresh download.

func DownloadWindowsISO 

func DownloadWindowsISO(ctx context.Context, home, language string, obs Observer) (string, error)

DownloadWindowsISO returns a cached Windows 11 ARM64 install ISO with complete media, downloading and assembling it when missing.

winkit's media.FetchWindowsISO serves the MCT catalog lane, which yields complete media, and its cache. Its UUP dump fallback (taken when the MCT catalog fails) builds boot-only media with no sources/install.wim, and the PE+WSL1 build extracts install.wim from the ISO, so boot-only media cannot feed it. Until winkit's fallback can assemble complete media, devcell runs UUP dump itself with BootOnly off whenever winkit returns boot-only media or fails. That ISO lives in fullMediaDir because both UUP dump lanes give their ISO the same file name and winkit's cache check cannot tell them apart.

func InstanceDir 

func InstanceDir(home, cellName string) string

InstanceDir returns the per-cell instance directory for Windows VMs. It is also winkit's state dir for the cell's VM (StartOpts.StateDir). Layout: ~/.devcell/<cellName>/windows/

func RenderWallpaper 

func RenderWallpaper(nixHome, cellID string) ([]byte, error)

RenderWallpaper renders the devcell wallpaper SVG to a PNG, substituting cellID for the {{CELL_ID}} placeholder. An empty cellID strips it. Returns nil, nil when the SVG or rsvg-convert is not available.

func ResolveWindowsISO 

func ResolveWindowsISO(envISO, configISO, home string) (string, error)

ResolveWindowsISO resolves the Windows ARM64 ISO path. Priority: env DEVCELL_WINKIT_WINDOWS_ISO > config path > cached download > error.

The cached download is looked up without touching the network: `cell build` must not start the multi-gigabyte download `cell init` owns.

func SetWallpaperGuestCommand 

func SetWallpaperGuestCommand(g guest, pngData []byte) string

SetWallpaperGuestCommand wraps SetWallpaperScript in a guest-executable command for a full Windows install (runs via Windows OpenSSH as the session user). PE mode is not supported (no Explorer shell).

func SetWallpaperScript 

func SetWallpaperScript(pngData []byte) string

SetWallpaperScript returns a PowerShell command that decodes a base64 PNG, writes it to C:\Windows\Web\Wallpaper\winkit\wallpaper.png, and applies it as the desktop wallpaper via SystemParametersInfo.

func StopVM 

func StopVM(ctx context.Context, home, cellName string) error

StopVM gracefully shuts down a running Windows VM for the given cell. It tries SSH shutdown first, then SIGTERM, then Kill.

func ValidateISO 

func ValidateISO(path string) error

ValidateISO checks that a file carries a recognised disc format by reading the volume descriptor at sector 16 (offset 0x8001). Both ISO 9660 (CD001) and UDF (BEA01/NSR02/NSR03) are accepted — Windows ARM64 ISOs built by UUP dump are pure UDF.

func VirtioISOPath 

func VirtioISOPath(home string) string

VirtioISOPath returns the path to the cached VirtIO drivers ISO, where winkit's media.FetchVirtioISO puts it.

Types

type AllocatedPorts 

type AllocatedPorts struct {
	SSHPort string
	VNCPort string
	RDPPort string
}

AllocatedPorts holds the cell-ID-derived port strings for SSH, VNC, and RDP.

func AllocatePorts 

func AllocatePorts(portPrefix string, taken map[int]struct{}) AllocatedPorts

AllocatePorts computes SSH, VNC, and RDP ports using the same cell-ID-based scheme as the Docker runner. portPrefix is SESSION_PORT_PREFIX + cellID. The taken map (may be nil) lists ports already in use by other processes.

func (AllocatedPorts) RDPPortUint16 

func (p AllocatedPorts) RDPPortUint16() uint16

RDPPortUint16 returns the RDP port as uint16.

func (AllocatedPorts) SSHPortUint16 

func (p AllocatedPorts) SSHPortUint16() uint16

SSHPortUint16 returns the SSH port as uint16.

func (AllocatedPorts) VNCPortUint16 

func (p AllocatedPorts) VNCPortUint16() uint16

VNCPortUint16 returns the VNC port as uint16.

type DiscoveredVM 

type DiscoveredVM struct {
	CellName  string
	PID       int
	ImagePath string
	Ports     VMPorts
}

DiscoveredVM is a running Windows VM found in a cell's instance dir.

func DiscoverRunningVMs 

func DiscoverRunningVMs(home string) []DiscoveredVM

DiscoverRunningVMs lists the live VMs winkit has registered under each cell's instance dir (~/.devcell/<cell>/windows/, see InstanceDir), which devcell passes to winkit.Start as the state dir.

func RunningVMForImage 

func RunningVMForImage(home, image string) (DiscoveredVM, bool)

RunningVMForImage returns a live VM, in any cell, booted from image.

type Engine 

type Engine struct{}

Engine implements engine.Engine for engine.Winkit.

func (Engine) Build 

func (Engine) Build(ctx context.Context, opts engine.BuildOpts) error

Build builds the cell's Windows guest image with go-winkit: a WinPE boot volume (stage pe-wsl) or a full Windows install (full-wsl), each with a WSL1 nix distro. Installer media (Windows ISO, VirtIO drivers) are downloaded automatically when missing. opts.Stack overrides opts.Cell.Stack. opts.Update and opts.Force set NoCache on the go-winkit build, forcing a fresh WSL distro. opts.NoCache and opts.Stage are not honored.

func (Engine) Init 

func (Engine) Init(ctx context.Context, opts engine.InitOpts) error

Init prepares directories and an SSH keypair and downloads the VirtIO drivers and Windows ARM64 ISO the build needs. It creates no VM; `cell build --engine winkit` does. opts.Stack overrides opts.Cell.Stack. opts.Force regenerates the keypair and downloads the VirtIO drivers again.

func (Engine) Run 

func (Engine) Run(ctx context.Context, opts engine.RunOpts) error

Run boots the cell's Windows guest via go-winkit and runs the agent in its WSL1 distro over SSH.

Lifecycle:

  1. Acquire the image (build it when missing)
  2. Boot the VM via winkit.Start, wait for the guest's SSH channel
  3. Run the agent inside WSL1 over that channel

Two args belong to cell and are taken out of opts.Args (takeRunArgs): --force sets opts.Force, and --stack=<name> overrides opts.Cell.Stack. opts.Force builds a missing image without asking. opts.Rebuild, opts.Update and opts.Background are not honored yet; the VM this call started is stopped when the agent exits. A non-zero agent exit is *engine.ExitError.

Off macOS with opts.Debug, every step is simulated and logged with a [MOCK] prefix; on macOS, opts.Debug logs the real steps via ux.Debugf.

type NopObserver 

type NopObserver struct{}

NopObserver silently discards all events.

func (NopObserver) Logf 

func (NopObserver) Logf(string, ...any)

func (NopObserver) Progress 

func (NopObserver) Progress(float64, string)

type Observer 

type Observer interface {
	Logf(format string, args ...any)
	Progress(fraction float64, message string)
}

Observer receives progress events from long-running QEMU operations.

type VMPorts 

type VMPorts struct {
	SSHPort uint16
	VNCPort uint16
	RDPPort uint16
}

VMPorts are the host ports a running VM forwards.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.