weaveplatform-agent-core

module

v0.5.0 Latest Latest Go to latest Published: Aug 25, 2026 License: MIT

README ¶

weaveplatform-agent

One agent, any device, physical or virtual. It presents a single install footprint, a single enrolment and a single identity to an administrator, and behind that runs one module per Weave product that has a device-side half.

Core is infrastructure with no opinion about what the platform does. It knows how to be one authenticated, policied, supervised presence on a machine. Modules are products — separate signed binaries, owned by product teams, shipped on their products' release trains, fetched and promoted at runtime. Core launches them Terraform-style: verify signature, spawn, handshake, speak gRPC over a local socket for the process lifetime.

The full architecture lives in spec.md — read it before changing anything here. docs/architecture.md shows what was built and how the pieces relate (with diagrams); docs/development.md covers local setup, running the agent, and the release pipeline.

Layout

One repository, two Go modules. The sdk is what a module builds against and is tagged on its own (sdk/vX.Y.Z) so a module can pin it independently of core; core builds the sdk it ships with. Products live in their own repositories and pin the sdk by version.

flowchart LR
    sdk["<b>sdk/</b><br/>module contract + runtime<br/>tags sdk/vX.Y.Z"] --> core["<b>.</b><br/>weaveboot · weave-agent · weavectl<br/>tags vX.Y.Z"]
    sdk -->|by version| product["product repos<br/>guestweave, deviceweave, …<br/>one module each"]
    channels["weaveplatform-channels<br/>signed channel manifests"] -. verified at runtime .-> core
    style core fill:#1f6feb,color:#fff

Path	What
`cmd/weave-agent`	Core: the supervised, enrolled presence on the machine
`cmd/weaveboot`	Supervises core so core can be replaced in place — staged, health-gated, with rollback
`cmd/weavectl`	Operator CLI over the control socket
`cmd/weavemanifest`	Mints and verifies the channel-manifest signing chain — verify is `internal/manifestverify`, so a manifest it accepts is one core accepts
`internal/supervise`	Module supervision: verify-before-exec, privilege drop, handshake, health, crash-loop breaker
`internal/lifecycle`	Module install: fetch, stage, health-gated promote, N-1 retention, rollback
`sdk/`	The module SDK, a nested Go module (`…/weaveplatform-agent/sdk`): `modulesdk`, `handshake`, `ipc`, `platform`, the generated protocol under `gen/`, `manifest` types, `hvchannel`. Everything a module imports, nothing it should not — see `sdk/README.md`
`modules/sysinfo`	The platform's own module and the template every product module is copied from; a nested Go module (tags `modules/sysinfo/vX.Y.Z`) that pins the sdk by version like any product would, and releases through the same reusable pipeline
`proto/`, `schema/`	The sources `sdk/gen` and the manifest JSON Schemas are generated from; `buf generate` regenerates and CI fails on drift
`test/protocompat`	The test that matters: core at protocol N accepts an N-1 module and cleanly refuses N-3

Building

CGO_ENABLED=0 go build ./...              # core; builds the sdk it ships with (replace => ./sdk)
cd sdk && CGO_ENABLED=0 go build ./...    # the sdk on its own recorded pins — what a module author gets

Zone A throughout: static, no cgo, macOS + Windows + Linux. Modules pin the sdk with require github.com/deploymenttheory/weaveplatform-agent-core/sdk vX.Y.Z. go install …/cmd/weavectl@vX is not supported — the root go.mod carries a replace, which go install pkg@version refuses; binaries ship as goreleaser archives and the deb.

Core is the single point of failure for the whole product line. That is the argument for keeping it aggressively boring.

Directories ¶

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

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.
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, enrolment, and per-module credential scoping.	Package identity owns who this device is: the keypair, enrolment, 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.
policy Package policy fetches, caches and delivers module policy.	Package policy fetches, caches and delivers module policy.
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.
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
test
stubgateweave Package stubgateweave is the stand-in server core develops against until GateWeave exists: enrolment, policy delivery, and artifact serving, just enough surface for core's clients to be real.	Package stubgateweave is the stand-in server core develops against until GateWeave exists: enrolment, policy delivery, and artifact serving, just enough surface for core's clients to be real.