agentembed

Documentation

Overview

Package agentembed exposes the Go source files for the in-guest binaries clawk ships: clawk-pty-agent (PTY-backed shell sessions over vsock), clawk-init (PID 1 for OCI-image sandboxes), and clawk-time-sync.

internal/guestbuild cross-compiles these on the host (GOOS=linux, CGO_ENABLED=0) and machine/oci injects the static binaries into the rootfs at disk-build time — arbitrary OCI images have no Go toolchain, so nothing is built in the guest.

Why the .go.in extension: the sources use Linux-only AF_VSOCK constants and their own go.mod files. A non-.go extension keeps the host's Go tooling from compiling them as part of the clawk module — `go build ./...` doesn't recurse into them and IDE indexers ignore them.

Index

• Constants
• Variables
• func SourcesHash() string
• type PrebuiltManifest
  • func Prebuilt() (files fs.FS, m PrebuiltManifest, ok bool)

Constants

const PrebuiltDir = "prebuilt"

PrebuiltDir is where `make guestbin` writes, relative to this package.

const PrebuiltManifestName = "manifest.json"

PrebuiltManifestName identifies the metadata `make guestbin` writes beside the binaries.

Variables

var AgentGoMod []byte

AgentGoMod is the go.mod used to build the agent. Lists only the agent's direct deps (creack/pty + golang.org/x/sys); `go mod tidy` resolves the rest.

var AgentMainGo []byte

AgentMainGo is the agent's main.go source, cross-compiled on the host by internal/guestbuild.

var InitGoMod []byte

InitGoMod is the matching go.mod for clawk-init.

var InitMainGo []byte

InitMainGo is the source of clawk-init — PID 1 for OCI-image sandboxes. internal/guestbuild cross-compiles it on the host and machine/oci injects the binary into the rootfs at disk-build time.

var SerialAgentTest []byte

SerialAgentTest is the agent's own test suite for the serial forwarder, run inside a throwaway module built from AgentMainGo — see TestSerialForwarderRuns. Embedded rather than kept as a normal _test.go for the same reason main.go.in is: it is package main in the guest's module, not in this one.

var TimeSyncGoMod []byte

TimeSyncGoMod is the matching go.mod for clawk-time-sync.

var TimeSyncMainGo []byte

TimeSyncMainGo is the source for the standalone clawk-time-sync binary that listens on vsock port 1025 and applies pushes from the host-side time-sync goroutine. Injected into the rootfs alongside clawk-pty-agent so guest clocks survive macOS standby.

Functions

func SourcesHash

func SourcesHash() string

SourcesHash digests every embedded guest source, in a fixed order. Both the generator and the consumer compute it the same way, so it can be compared across a build boundary.

Types

type PrebuiltManifest

type PrebuiltManifest struct {
	// Arch is the GOARCH the binaries were built for. Guest arch always
	// equals host arch (hardware virtualization can't cross architectures),
	// but recording it means a mismatch is caught rather than assumed.
	Arch string `json:"arch"`

	// SourcesSHA256 is SourcesHash() at build time. It is the one thing worth
	// verifying: it catches an artifact whose embedded binaries were built
	// from different .in sources than the ones embedded beside them, which is
	// otherwise invisible and would ship a guest that silently predates the
	// source tree.
	SourcesSHA256 string `json:"sources_sha256"`

	// GoVersion built them, for diagnostics.
	GoVersion string `json:"go_version,omitempty"`
}

PrebuiltManifest describes what the embedded binaries are, so a consumer can refuse a set that doesn't match what it needs.

func Prebuilt

func Prebuilt() (files fs.FS, m PrebuiltManifest, ok bool)

Prebuilt returns the embedded binaries and their manifest.

ok is false for an ordinary source build, where the directory holds no payload — that is the normal case for contributors, not an error.