agent

Documentation

Overview

Package agent carries the compiled komizo-box binaries, so that installing one is something `komizo init` can do over a plain SSH connection.

EMBEDDED rather than downloaded. init already works on a box with nothing on it but sshd, and making it fetch a release URL would add a network dependency and a supply-chain step to the one operation that is supposed to work when very little else does. It is also the pattern komizo already uses for the provisioning shell -- see scripts/embed.go -- for the same reason.

The cost is the CLI's size, and one build-order constraint: the binaries have to EXIST before the CLI is compiled, because //go:embed reads the filesystem at build time and cannot invoke a compiler. `make agents` builds them; the release workflow runs it. A CLI built without that step still compiles and still does everything else -- the failure is one clear message at the moment somebody tries to install an agent, rather than a build nobody can run.

Index

• Variables
• func ArchFor(uname string) (string, bool)
• func BuiltStamp(version string) string
• func ByVersion(stamp string) bool
• func For(arch string) ([]byte, error)
• func Get(ctx context.Context, modulePath, version, arch string) ([]byte, string, error)
• func Stamp() string

Variables

var Arches = []string{"amd64", "arm64"}

Arches are the architectures komizo ships an agent for.

Two, because they are what servers are. amd64 is every ordinary VPS, and arm64 is the cheap tier at most providers -- Hetzner, Oracle, AWS Graviton -- which is exactly the tier a project running its own boxes ends up on.

Functions

func ArchFor

func ArchFor(uname string) (string, bool)

ArchFor maps what `uname -m` says to what komizo builds.

The box is asked rather than assumed. komizo is pointed at other people's servers, and a laptop's architecture says nothing about theirs -- installing an amd64 binary on an arm64 box produces "not found" from the kernel, which is the single most confusing thing an exec can say.

func BuiltStamp

func BuiltStamp(version string) string

BuiltStamp is what a compiled-on-demand agent records on the box.

The "v:" prefix is load-bearing: it is how anything reading the stamp knows it is a version rather than a content hash, and therefore that comparing it to a hash says nothing. See agentBehind.

func ByVersion

func ByVersion(stamp string) bool

ByVersion reports whether a stamp names a version rather than hashing content.

func For

func For(arch string) ([]byte, error)

For returns the embedded agent for one architecture, and only that.

func Get

func Get(ctx context.Context, modulePath, version, arch string) ([]byte, string, error)

Get is the agent for one architecture, however this komizo can produce one.

EMBEDDED FIRST, BUILT SECOND. A release archive carries the agents and needs no toolchain, which is what makes `komizo init` work on a machine with no Go on it. A `go install`/`go run` build carries none -- the agents are gitignored build artifacts, so the module the proxy serves has only bin/.keep -- and for that case the agent is compiled from the same module at the same version.

modulePath and version are the running komizo's own, passed in rather than discovered here: this package must not be the thing that decides what version of itself to install, because getting that wrong installs an agent that does not match the CLI managing the box. The second return is the STAMP to record on the box -- what komizo installed there -- and it differs by path for a reason that matters.

An embedded agent stamps by CONTENT, over every architecture, so the same release produces the same stamp whatever box it is talking to. A built one cannot: -trimpath and CGO_ENABLED=0 make the output reproducible across machines but not across TOOLCHAINS, so two operators on different Go versions would produce different bytes from identical source and each would read the other's box as out of date. Forever. That is precisely the never-settling false alarm this project keeps deleting.

So a built agent stamps by VERSION, marked with a "v:" prefix so a reader can tell the two apart rather than comparing a hash against a version string and concluding something is wrong. Version is the honest identity here: the agent was compiled from a pinned module version, and that is exactly what decides whether running the update would change anything.

func Stamp

func Stamp() string

Stamp is the content hash of every agent this komizo carries.

What it answers is "would running the update change anything" -- so it is over the bytes that would be installed, and it covers ALL architectures so that the same komizo produces the same stamp whatever box it is talking to. A per-architecture stamp would make two boxes disagree about whether they were up to date while running the same release.

Empty when no agent is embedded, which reads as "nothing to install" rather than as a hash of nothing.