| name | agentos-image-builds |
| description | Build, test, and publish OCI images safely from an exact Git revision inside or outside an AgentOS Fleet. Use when a First or Second Mate needs an unreleased image, must choose BuildKit or Buildah for an in-cluster build, or needs to make an immutable image digest available to Kubernetes without a host runtime socket. |
Build Fleet images
- Resolve the exact committed Git revision, Dockerfile, target platforms, existing builder, target registry and node pull path. Stop on uncommitted source unless the Captain explicitly chooses a disposable local experiment that will not be represented as a release.
- Load
$agentos-registry when no approved registry and node-reachable pull path already exist. Ask before credentials, registry creation, cluster mutation, cost or external exposure.
- Prefer an existing reviewed platform build service. For a new in-cluster path, start from the current official BuildKit Kubernetes examples and rootless guidance:
- on a compatible Kubernetes and runtime, prefer a one-shot BuildKit Job with a Pod user namespace (
hostUsers: false);
- otherwise use rootless BuildKit only after its user-namespace, seccomp/AppArmor, snapshotter and storage requirements pass a lifecycle test;
- use Buildah as a maintained alternative only where its unshare, UID/GID mappings and storage driver are verified.
- Discover the current supported builder version from official documentation or releases and pin its image by digest. Do not introduce archived Kaniko, mount a host Docker/containerd socket, or grant host-namespace privilege as a shortcut. Root inside a Pod user namespace remains unprivileged on the host and can still execute ordinary package-installing Dockerfile steps; verify host support rather than assuming it.
- Mount registry authentication through a reviewed Secret, workload identity or credential provider. Never place credentials in command arguments, image layers, build context or logs.
- Build the exact commit with native
buildctl or buildah, push it, read the registry-confirmed digest and use only name@sha256:... for testing or deployment. Verify that the target kubelet can pull that digest before changing a Mate.
- Preserve build logs, source revision, builder identity and resulting digest as evidence. Roll out one Mate at a time and keep the previous digest available for rollback.
Treat vCluster shared nodes as host-node builds and pulls: the host runtime, filesystem and policy still determine support.
The AgentOS image contains a portable shallow Git seed. When building from a linked worktree, use a remote Git context at the exact pushed commit with BuildKit's BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 build argument instead of sending the worktree's host-specific .git indirection as a local build context. Set AGENTOS_GIT_REMOTE to the credential-free fork or project URL and keep AGENTOS_GIT_UPSTREAM on the public AgentOS upstream when appropriate.
