README
¶
weaveplatform-agent-core
The weave agent core: one agent for any device or container, physical or virtual — a
laptop, a VM on that laptop, a VM on a cloud host, a container on a device or in the cloud.
It presents a single install footprint and a single identity to an administrator, and
behind that it verifies, runs and supervises modules: separate signed binaries, one per
capability per OS (weave-linux-presence, weave-windows-exec, …), fetched and promoted at
runtime from a signed channel.
Core is driven by the host directly outside it, over one authenticated host channel: the
hypervisor of a VM, or the runtime of a container
(docs/architecture.md).
Core is infrastructure with no opinion about what the platform does. It knows how to be one authenticated, policied, supervised presence on a machine, and nothing about what a module is for. That keeps the single point of failure for the whole product line boring.
The Terraform model
Core is to its modules what Terraform core is to providers
(docs/decisions/0001):
| Terraform | Weave |
|---|---|
hashicorp/terraform: the CLI and core; owns the plugin protocol (docs/plugin-protocol/*.proto) and keeps a private implementation (internal/tfplugin5, internal/plugin) |
this repository: weave-agent, weaveboot, weavectl, weavemanifest; owns proto/ and schema/; private implementation under internal/ |
terraform-plugin-go, -framework, -testing, and every provider in its own repository |
weaveplatform-agent-modules: the module SDK and every weave-<os>-<capability> module, each with its own release |
| The Terraform Registry | weaveplatform-release-channels: signed channel manifests saying which module versions a device may run |
Core launches modules the same way Terraform launches providers: verify the signature,
spawn, handshake, then speak gRPC over a local socket for the process lifetime. Core and
modules agree on the wire, never on a Go package: core imports nothing from
weaveplatform-agent-modules, and CI fails if it does.
flowchart LR
proto["<b>proto/ · schema/</b><br/>the protocol, owned by core"] --> core["<b>weaveplatform-agent-core</b><br/>weaveboot · weave-agent · weavectl · weavemanifest<br/>internal/protocol · internal/gen<br/>tags vX.Y.Z"]
proto -. "the contract" .-> modules["<b>weaveplatform-agent-modules</b><br/>the module SDK<br/>weave-<os>-<capability> modules"]
modules <-. "the wire: handshake + gRPC" .-> core
modules -->|publish + promote| channels["<b>weaveplatform-release-channels</b><br/>signed channel manifests"]
channels -. verified at runtime .-> core
style core fill:#1f6feb,color:#fff
The full architecture is in spec.md; read it before changing anything here.
docs/ covers how the pieces fit, the protocol and its versioning, the
service map, packaging, and development.
Layout
One repository, one Go module, github.com/weaveplatform/weaveplatform-agent-core.
| Path | What |
|---|---|
cmd/weave-agent |
Core: the supervised, authenticated presence on the machine |
cmd/weaveboot |
Supervises core so core can be replaced in place — staged, health-gated, with rollback; on Windows also the WeaveAgent service and its installer (docs/windows-install.md) |
cmd/weavectl |
Operator CLI over the control socket |
cmd/weavemanifest |
Mints and verifies the channel-manifest signing chain; its verify is internal/manifestverify, so a manifest it accepts is one core accepts |
internal/supervise |
Module supervision: verify-before-exec, privilege drop, per-user console sessions, handshake, health, crash-loop breaker |
internal/lifecycle |
Module install: fetch, stage, health-gated promote, N-1 retention, rollback |
internal/hostserv, internal/controlsock |
The host services modules call, and the operator control socket |
internal/verify, internal/manifestverify |
Binary signatures per OS, and the signed channel manifest |
internal/transport, internal/capability |
The host channel (virtio-serial, vsock, HvSocket, Unix socket) and the capability probe |
internal/store, internal/identity, internal/policy, internal/eventbus, internal/session |
Encrypted store, device identity, policy delivery, event bus, console sessions |
internal/weaveboot, internal/winsvc, internal/certtrust, internal/layout |
Core replacement, the Windows service and its installer, the Windows trust in module signatures, the on-disk layout |
internal/core, internal/retry, internal/wlog, internal/werror, internal/platform, internal/version |
Core's wiring and protocol window; backoff, logging, error conventions, the OS seam, the build version |
internal/protocol |
Core's own implementation of the wire: handshake, ipc, hvchannel, manifest |
internal/gen |
Generated from proto/ by buf generate; committed, and CI fails if it drifts |
proto/, schema/ |
The protocol (weave/agent/v1, weave/control/v1) and the manifest JSON Schemas |
internal/provision |
The channel trust anchor from a host-supplied provisioning volume, for guests without cloud-init |
packaging/ |
The deb (systemd unit and scripts), the macOS package (launchd daemon and scripts), the Windows installer, uninstaller, code-signing certificate and signing script, the apt repository tool, the cloud-init bring-up seed |
test/protocompat |
Core at protocol N accepts a pinned N-1 module and cleanly refuses one outside the window |
Building
make build # every cmd/* binary for linux, darwin, windows × amd64, arm64 into bin/
make gate # everything CI runs: vet, lint, test, coverage, govulncheck, build, protocol checks
Everything is pure Go and builds with CGO_ENABLED=0 for every platform. The Makefile sets
GOWORK=off. docs/development.md covers the tools, running the
agent locally, and testing.
Releasing
release-please keeps a release PR open on main; merging it tags vX.Y.Z, and the tag runs
goreleaser: per-platform archives of the four binaries, the weave-agent .deb, and a
checksum file signed keylessly with cosign; a macOS runner then builds the
weave-agent_<version>_darwin_arm64.pkg installer from the released binaries
(docs/macos-package.md). The Windows binaries and install scripts
are Authenticode signed with the weaveplatform code-signing certificate before they are
archived, and a Windows runner installs the zip, checks every signature and uninstalls it
again (docs/windows-install.md). Core ships no modules. See
docs/development.md.
Writing a module
Modules are not written here. Build against the module SDK,
github.com/weaveplatform/weaveplatform-agent-modules/sdk, starting from
sdk/docs/writing-a-module.md
in weaveplatform-agent-modules, where every module lives.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
weave-agent
command
Command weave-agent is core: the one authenticated, policied, supervised presence on a machine.
|
Command weave-agent is core: the one authenticated, policied, supervised presence on a machine. |
|
weaveboot
command
Command weaveboot supervises core so core can be replaced in place: staged, health-gated, with rollback.
|
Command weaveboot supervises core so core can be replaced in place: staged, health-gated, with rollback. |
|
weavectl
command
Command weavectl is the operator CLI over core's control socket.
|
Command weavectl is the operator CLI over core's control socket. |
|
weavemanifest
command
Command weavemanifest mints and verifies the channel-manifest signing chain: an offline root key endorses named signing keys; signing keys sign channel manifests.
|
Command weavemanifest mints and verifies the channel-manifest signing chain: an offline root key endorses named signing keys; signing keys sign channel manifests. |
|
internal
|
|
|
capability
Package capability performs the one host inventory at startup.
|
Package capability performs the one host inventory at startup. |
|
certtrust
Package certtrust puts a self-signed code-signing certificate into the Windows machine's trust, and takes it out again: the install-time, out-of-band step that lets WinVerifyTrust accept modules signed with it.
|
Package certtrust puts a self-signed code-signing certificate into the Windows machine's trust, and takes it out again: the install-time, out-of-band step that lets WinVerifyTrust accept modules signed with it. |
|
controlsock
Package controlsock serves ControlService: the one endpoint for weavectl and, later, the portal.
|
Package controlsock serves ControlService: the one endpoint for weavectl and, later, the portal. |
|
core
Package core wires the agent together and runs it.
|
Package core wires the agent together and runs it. |
|
eventbus
Package eventbus is core's in-process pub/sub: the only lateral channel between modules.
|
Package eventbus is core's in-process pub/sub: the only lateral channel between modules. |
|
hostserv
Package hostserv serves core's host services to modules, one gRPC server per module socket.
|
Package hostserv serves core's host services to modules, one gRPC server per module socket. |
|
identity
Package identity owns who this device is: the keypair, the device id, and per-module credential scoping.
|
Package identity owns who this device is: the keypair, the device id, and per-module credential scoping. |
|
layout
Package layout resolves where core keeps things.
|
Package layout resolves where core keeps things. |
|
lifecycle
Package lifecycle owns module install: fetch, verify, stage alongside, health-gated promote, N-1 retention, rollback.
|
Package lifecycle owns module install: fetch, verify, stage alongside, health-gated promote, N-1 retention, rollback. |
|
manifestverify
Package manifestverify verifies the channel-manifest signing chain: the offline root key (embedded in core) endorses a signing key, the signing key signs the channel manifest.
|
Package manifestverify verifies the channel-manifest signing chain: the offline root key (embedded in core) endorses a signing key, the signing key signs the channel manifest. |
|
platform
Package platform is the deliberately thin OS seam.
|
Package platform is the deliberately thin OS seam. |
|
policy
Package policy loads, caches and delivers module policy.
|
Package policy loads, caches and delivers module policy. |
|
protocol/handshake
Package handshake is the shared vocabulary of the core↔module handshake: the environment core sets, the one stdout line the module answers with, and the exit code that means "protocol out of window".
|
Package handshake is the shared vocabulary of the core↔module handshake: the environment core sets, the one stdout line the module answers with, and the exit code that means "protocol out of window". |
|
protocol/hvchannel
Package hvchannel is the framing and addressing format of the hypervisor channel — the single byte pipe (virtio-serial / vsock / HvSocket) between core running inside a guest and the host tooling outside it.
|
Package hvchannel is the framing and addressing format of the hypervisor channel — the single byte pipe (virtio-serial / vsock / HvSocket) between core running inside a guest and the host tooling outside it. |
|
protocol/ipc
Package ipc owns local transport: Unix domain sockets on macOS and Linux, named pipes on Windows, behind one Listen/Dial seam so neither core nor a module runtime carries per-OS socket code at call sites.
|
Package ipc owns local transport: Unix domain sockets on macOS and Linux, named pipes on Windows, behind one Listen/Dial seam so neither core nor a module runtime carries per-OS socket code at call sites. |
|
protocol/manifest
Package manifest carries the Go types for the module manifest (schema/module-manifest.schema.json): the document every module authors, embeds, and publishes, and that core gates launch decisions on.
|
Package manifest carries the Go types for the module manifest (schema/module-manifest.schema.json): the document every module authors, embeds, and publishes, and that core gates launch decisions on. |
|
provision
Package provision installs the hypervisor channel's trust anchor from host-supplied boot media, for guests that have no cloud-init to do it: macOS and Windows.
|
Package provision installs the hypervisor channel's trust anchor from host-supplied boot media, for guests that have no cloud-init to do it: macOS and Windows. |
|
registry
Package registry is core's one table of installed modules: what each is, where it answers on the host channel, and what state it is in.
|
Package registry is core's one table of installed modules: what each is, where it answers on the host channel, and what state it is in. |
|
retry
Package retry provides exponential backoff with jitter.
|
Package retry provides exponential backoff with jitter. |
|
session
Package session reports which user owns the console — the logged-in user whose desktop is on the physical display — so the supervisor can run per-user-console modules inside that user's session.
|
Package session reports which user owns the console — the logged-in user whose desktop is on the physical display — so the supervisor can run per-user-console modules inside that user's session. |
|
store
Package store is core's durable, encrypted key/value store: one bbolt file owned by core, one bucket per module namespace, every value sealed with AES-256-GCM under a master key the platform protector guards.
|
Package store is core's durable, encrypted key/value store: one bbolt file owned by core, one bucket per module namespace, every value sealed with AES-256-GCM under a master key the platform protector guards. |
|
store/keyprotect
Package keyprotect owns the store master key's at-rest protection.
|
Package keyprotect owns the store master key's at-rest protection. |
|
supervise
Package supervise owns module processes: spawn, verify-before-exec, handshake, health, crash-loop damping, and a start-limit (restart budget).
|
Package supervise owns module processes: spawn, verify-before-exec, handshake, health, crash-loop damping, and a start-limit (restart budget). |
|
transport
Package transport is core's channel mux: modules address a peer, core routes.
|
Package transport is core's channel mux: modules address a peer, core routes. |
|
verify
Package verify authenticates module binaries before exec.
|
Package verify authenticates module binaries before exec. |
|
version
Package version carries core's build identity, stamped at link time:
|
Package version carries core's build identity, stamped at link time: |
|
weaveboot
Package weaveboot supervises core so core can be replaced in place.
|
Package weaveboot supervises core so core can be replaced in place. |
|
werror
Package werror carries the platform's error conventions: sentinel errors for conditions callers branch on, and wrapping helpers that keep module and operation context attached.
|
Package werror carries the platform's error conventions: sentinel errors for conditions callers branch on, and wrapping helpers that keep module and operation context attached. |
|
winsvc
Package winsvc runs weaveboot as a Windows service and registers it with the Service Control Manager — the Windows counterpart of the systemd unit (packaging/linux/weave-agent.service) and the launchd plist.
|
Package winsvc runs weaveboot as a Windows service and registers it with the Service Control Manager — the Windows counterpart of the systemd unit (packaging/linux/weave-agent.service) and the launchd plist. |
|
wlog
Package wlog constructs the platform's loggers.
|
Package wlog constructs the platform's loggers. |
|
packaging
|
|
|
apt/aptrepo
command
Command aptrepo turns a directory of .deb files into a signed flat apt repository.
|
Command aptrepo turns a directory of .deb files into a signed flat apt repository. |
|
sdk
module
|
Click to show internal directories.
Click to hide internal directories.