README
¶
guestweave
The in-guest half of VM management, and the product repository it belongs to.
A hypervisor can create, run, snapshot and cut power to a guest from outside.
It cannot shut the OS down cleanly, run a process inside it, learn the address
DHCP actually assigned, or correct a clock that resumed days behind. This repo
holds the module that does those things from inside, the wire vocabulary both
ends speak, and the host-side client the weave CLIs use to ask.
module/ the weaveplatform module a guest runs — one binary per platform,
OS backends selected by build tag; module.manifest.json is the
only list of platforms. Its own Go module: it is the only thing
that links the OS bindings, and a host CLI importing pkg/ must
not inherit them (guestweave-macos is on an older
go-bindings-macosplatform than the guest backend needs)
pkg/
guestwire the vocabulary: command kinds, payloads, envelope, stream chunks
guestagent dispatcher, guest→host events, stream writing
guestmodule the modulesdk.Module every build shares; backend interfaces
guestexec process execution and stdio streaming (pty, ConPTY)
guestpolicy exec authorisation and audit
guestpower the shared Unix power backend
guesthost the HOST end — a typed client per operation, imported by the CLIs
docs/ how a command reaches a backend, and the ordering contracts
handoff/ what has never run where, and how to run it
The module builds against the platform SDK by version
(github.com/deploymenttheory/weaveplatform-agent-core/sdk) and is loaded by
core like any other module: verified, spawned, handshaken, supervised. Core
never interprets the payloads — everything under pkg/guestwire is product
vocabulary and stays here.
Building
CGO_ENABLED=0 go build ./... # pkg/ (this OS)
cd module && CGO_ENABLED=0 go build . # the guest binary (this OS)
cd module && CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build . # any platform in the manifest
sh module/packaging/build-deb.sh arm64 # the Linux package
module/go.mod replaces github.com/deploymenttheory/guestweave-agent with ../, so the binary
always builds against the pkg/ it ships with; nothing fetches the binary as a Go module.
Zone A: pure Go, no cgo, every platform cross-compiles from any host. The
three house binding SDKs (go-bindings-macosplatform, -win32, -wmi) are
pure Go too.
Releasing
Conventional commits accumulate; release-please opens release X.Y.Z,
stamping module/module.manifest.json; merging tags vX.Y.Z, and
.github/workflows/release.yml hands the tag to the platform repository's
reusable module pipeline, which builds every declared platform, pushes the
artifacts to ghcr.io/deploymenttheory/weaveplatform-modules/guestweave:X.Y.Z
with a digest-stamped sidecar, attaches the debs, and asks the channels
repository to open a promotion PR.
What is not here
The host CLIs (guestweave-macos, guestweave-windows) drive VMs from
outside and import pkg/guesthost and pkg/guestwire from here by version.
They may move in later; the layout leaves cmd/ free for them.
Directories
¶
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
guestagent
Package guestagent is the OS-agnostic runtime shared by the three guestweave modules: it reads inbound commands from core's hypervisor transport, routes each by kind to a registered handler, and sends the reply back over the same channel.
|
Package guestagent is the OS-agnostic runtime shared by the three guestweave modules: it reads inbound commands from core's hypervisor transport, routes each by kind to a registered handler, and sends the reply back over the same channel. |
|
guestexec
Package guestexec runs processes inside a guest and streams their stdio back over the hypervisor channel.
|
Package guestexec runs processes inside a guest and streams their stdio back over the hypervisor channel. |
|
guesthost
Package guesthost is the HOST end of the guestweave channel: the side that issues commands, not the side that answers them.
|
Package guesthost is the HOST end of the guestweave channel: the side that issues commands, not the side that answers them. |
|
guestmodule
Package guestmodule is the OS-agnostic guestweave module: it implements modulesdk.Module once, wires the guestagent Dispatcher to core's hypervisor transport, and registers a handler for each feature the OS supplies a backend for.
|
Package guestmodule is the OS-agnostic guestweave module: it implements modulesdk.Module once, wires the guestagent Dispatcher to core's hypervisor transport, and registers a handler for each feature the OS supplies a backend for. |
|
guestpolicy
Package guestpolicy is the guest-side control on what a host may run inside a guest, plus the audit record of what it actually ran.
|
Package guestpolicy is the guest-side control on what a host may run inside a guest, plus the audit record of what it actually ran. |
|
guestpower
Package guestpower is the Unix half of guestweave's graceful power feature.
|
Package guestpower is the Unix half of guestweave's graceful power feature. |
|
guestwire
Package guestwire is the OS-agnostic wire vocabulary the three guestweave modules and the host CLI both speak.
|
Package guestwire is the OS-agnostic wire vocabulary the three guestweave modules and the host CLI both speak. |