Files
skills/public/hip-0033.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

480 lines
34 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-0033</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hip-0033.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-0033">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-0033.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hip-0033</h1><p class="lede">HIP-33: Container Registry Standard. Status Final. Hanzo architectural specification.</p><h1>HIP-0033: Container Registry Standard</h1>
<h2>Abstract</h2>
<p>The fleet registry is <strong><code>oci.hanzo.ai</code></strong> — an OCI registry backed by our own object store, authenticated by Hanzo IAM, with repositories org-namespaced as <code>oci.hanzo.ai/&lt;org&gt;/&lt;app&gt;</code>. Images and Helm charts share the one store; 190 CD Applications pull <code>oci.hanzo.ai/charts</code> on every sync, so it is load-bearing rather than an experiment.</p>
<p><code>ghcr.io/&lt;org&gt;</code> keeps one purpose: <strong>already-published open-source artifacts that outside users pull</strong>. It is not a mirror and not a fallback.</p>
<p><strong>This is a target, and the migration is unfinished.</strong> Measured on 2026-09-09, most first-party workloads still resolve from GHCR and 13 resolve from <code>oci.hanzo.ai</code>; the counts are in §Conformance status. What is settled is the direction and the rules below, not the current distribution.</p>
<p><strong>Repository</strong>: <a href="https://github.com/hanzoai/registry">github.com/hanzoai/registry</a></p>
<p>The org prefix never mixes. Hanzo publishes under <code>hanzoai</code>, Lux under <code>luxfi</code>, Zoo under <code>zooai</code>, on whichever of the two hosts applies. A Lux image under a Hanzo prefix is a defect regardless of which registry it sits in.</p>
<h2>Design Philosophy</h2>
<h3>Why our own registry</h3>
<p><strong>Quotas.</strong> The move off GHCR as the push target was to escape a third party&#x27;s push and artifact quotas. A build fleet that cannot push because a monthly allowance ran out is not a build fleet.</p>
<p><strong>Speed.</strong> Service images carrying model weights, a CUDA runtime and a Python dependency tree run to 5-15 GB. Pulling that across the public internet takes minutes; pulling it from a registry on the same fabric takes seconds. In a rolling deployment every second of pull time extends the rollout window.</p>
<p><strong>Availability.</strong> If the registry a cluster pulls from is somebody else&#x27;s, that company&#x27;s outage is our inability to schedule a pod. Running pods survive; new ones do not start.</p>
<p><strong>One store for images and charts.</strong> A chart and the image it deploys are one release. Keeping them in two systems means two authentications, two retention policies, and two ways for a chart to reference an image that was never published.</p>
<h3>Why IAM authorizes the pull, and there is no registry password</h3>
<p>Per-repository authorization happens at <code>hanzo.id/v1/iam/registry/token</code> (HIP-0111): a client presents an IAM identity and receives a token scoped to the repository it asked for. There is no registry account, no shared push password and no per-repo credential to rotate — the same rule as everywhere else in the estate, that IAM is the sole authority for identity and tokens.</p>
<p>A build reaches the registry through the public ingress exactly as an outside client does, so a build is granted no path an external client would not have. The registry Service itself is not opened to the build fleet.</p>
<h3>How It Connects to Other HIPs</h3>
<pre><code>HIP-0036 (CI/CD Build System Standard)
| Defines HOW images are built (buildx, multi-arch, caching)
|
+---&gt; HIP-0033 (this) Container Registry Standard
Defines WHERE images go and HOW they are authenticated
HIP-0014 (Application Deployment)
|
+---&gt; Pulls images FROM registries defined in HIP-0033</code></pre>
<p>Build (HIP-0036) produces artifacts. Registry (HIP-0033) stores and distributes them. Deployment (HIP-0014) consumes them. Each HIP owns exactly one concern.</p>
<h2>Specification</h2>
<h3>OCI Compliance</h3>
<p>All Hanzo registries MUST implement the OCI Distribution Specification v1.1. This includes:</p>
<ul><li>Content-addressable storage using SHA-256 digests</li><li>Manifest and manifest list (multi-arch index) support</li><li>Blob upload (monolithic and chunked)</li><li>Tag listing and deletion</li><li>Referrers API for artifact relationships</li></ul>
<h3>Image Naming Convention</h3>
<p>Images follow a strict naming hierarchy:</p>
<pre><code># The fleet registry — the push target and the pull source
oci.hanzo.ai/&lt;org&gt;/&lt;app&gt;:{tag}
# Charts, in the same store
oci.hanzo.ai/charts/&lt;chart&gt;:{version}
# Published open source, for outside users only
ghcr.io/&lt;org&gt;/&lt;app&gt;:{tag}</code></pre>
<p><code>&lt;app&gt;</code> MUST match the repository name, and <code>&lt;org&gt;</code> MUST be the repository&#x27;s own org. Examples:</p>
<p>| Repository | Fleet image | Published OSS image | |---|---|---| | <code>hanzoai/iam</code> | <code>oci.hanzo.ai/hanzoai/iam</code> | <code>ghcr.io/hanzoai/iam</code> | | <code>hanzoai/cloud</code> | <code>oci.hanzo.ai/hanzoai/cloud</code> | <code>ghcr.io/hanzoai/cloud</code> | | <code>luxfi/node</code> | <code>oci.hanzo.ai/luxfi/node</code> | <code>ghcr.io/luxfi/node</code> | | <code>zooai/&lt;app&gt;</code> | <code>oci.hanzo.ai/zooai/&lt;app&gt;</code> | <code>ghcr.io/zooai/&lt;app&gt;</code> |</p>
<p>There is no Docker Hub target. A &quot;convenience mirror&quot; a build is permitted to fail produces tags that disagree with the source of truth, at a cadence nobody watches, and a consumer cannot tell which they pulled.</p>
<h3>Tag Strategy</h3>
<p>Tags convey meaning. Every image MUST be tagged according to this scheme:</p>
<p>| Tag Pattern | Meaning | Mutable | Example | |---|---|---|---| | <code>latest</code> | Most recent build from default branch | Yes | <code>iam:latest</code> | | <code>{semver}</code> | Semantic version from release | No | <code>iam:1.584.0</code> | | <code>{branch}-{sha}</code> | Branch build with commit SHA | No | <code>iam:main-a1b2c3d</code> | | <code>{branch}</code> | Latest build from named branch | Yes | <code>iam:main</code> |</p>
<p>Immutable tags (semver, branch-sha) MUST NOT be overwritten. Mutable tags (<code>latest</code>, branch-only) are updated on each push to the corresponding branch.</p>
<h3>Multi-Architecture Support</h3>
<p>All images MUST be built as multi-architecture manifest lists supporting:</p>
<ul><li><code>linux/amd64</code> - Standard x86_64 servers and CI runners</li><li><code>linux/arm64</code> - ARM servers (Graviton, Ampere) and Apple Silicon dev</li></ul>
<p>The build uses Docker Buildx with QEMU emulation for cross-compilation:</p>
<pre><code class="lang-yaml"># From actual CI workflow
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build and push
uses: docker/build-push-action@v5
with:
platforms: linux/amd64,linux/arm64
push: true</code></pre>
<h3>Image Variants</h3>
<p>Some services provide multiple image variants via Dockerfile multi-stage targets:</p>
<p>| Target | Suffix | Purpose | |---|---|---| | <code>STANDARD</code> | (none) | Production image, minimal footprint | | <code>ALLINONE</code> | <code>-allinone</code> | Self-contained with embedded database | | <code>DEV</code> | <code>-dev</code> | Development image with debug tools |</p>
<p>Example:</p>
<pre><code>ghcr.io/hanzoai/iam:latest # STANDARD target
ghcr.io/hanzoai/iam-allinone:latest # ALLINONE target</code></pre>
<h3>Metadata Labels</h3>
<p>All images MUST include OCI standard labels via the <code>metadata-action</code>:</p>
<pre><code class="lang-yaml">- name: Extract metadata
uses: docker/metadata-action@v5
with:
images: ghcr.io/hanzoai/{service}
tags: |
type=ref,event=branch
type=semver,pattern={{version}}
type=raw,value=latest,enable={{is_default_branch}}
type=sha,prefix={{branch}}-</code></pre>
<p>This produces labels including:</p>
<ul><li><code>org.opencontainers.image.source</code> - Link to source repository</li><li><code>org.opencontainers.image.version</code> - Semantic version</li><li><code>org.opencontainers.image.revision</code> - Git commit SHA</li><li><code>org.opencontainers.image.created</code> - Build timestamp</li></ul>
<h3>Garbage Collection</h3>
<p>The in-cluster registry MUST run garbage collection to reclaim storage from unreferenced layers. Policy:</p>
<ul><li><strong>Untagged manifests</strong>: Delete after 24 hours</li><li><strong>Unused layers</strong>: Delete when no manifest references them</li><li><strong>Retention</strong>: Keep the last 10 tagged versions per repository</li><li><strong>Schedule</strong>: Run GC daily at 03:00 UTC during low-traffic window</li></ul>
<h3>Webhook Notifications</h3>
<p>The registry MUST emit webhook notifications on image push events. These notifications drive downstream automation:</p>
<pre><code class="lang-json">{
&quot;events&quot;: [{
&quot;action&quot;: &quot;push&quot;,
&quot;target&quot;: {
&quot;repository&quot;: &quot;hanzoai/iam&quot;,
&quot;tag&quot;: &quot;latest&quot;,
&quot;digest&quot;: &quot;sha256:abc123...&quot;,
&quot;mediaType&quot;: &quot;application/vnd.oci.image.manifest.v1+json&quot;
},
&quot;timestamp&quot;: &quot;2025-01-15T10:30:00Z&quot;,
&quot;actor&quot;: {
&quot;name&quot;: &quot;github-actions&quot;
}
}]
}</code></pre>
<p>Consumers include:</p>
<ul><li>Kubernetes deployment controllers (trigger rollout on new <code>:latest</code>)</li><li>Vulnerability scanners (scan new images on push)</li><li>Audit logging (record who pushed what and when)</li></ul>
<h2>Implementation</h2>
<h3>Build and Push Pipeline</h3>
<p>The pipeline is HIP-0036&#x27;s and is not restated here: one reusable workflow in <code>hanzoai/ci</code>, imported by a short <code>.hanzo/workflows/cicd.yml</code>, driven by the repository&#x27;s <code>hanzo.yml</code>. No repository writes its own push steps.</p>
<p>What this HIP states about the push:</p>
<ol><li><strong>One destination.</strong> The build pushes to <code>oci.hanzo.ai/&lt;org&gt;/&lt;app&gt;</code>. There is</li></ol>
<p> no second push, no mirror, and no <code>continue-on-error</code> publication lane.</p>
<ol><li><strong>The credential is an IAM token, obtained per repository.</strong> The build</li></ol>
<p> authenticates to <code>hanzo.id/v1/iam/registry/token</code> with its machine identity and receives a token scoped to the repository it named. No registry password exists to store, leak or rotate.</p>
<ol><li><strong>The push crosses the public ingress</strong>, exactly as an outside client&#x27;s would.</li></ol>
<p> The registry Service is not reachable from the build fleet directly, so a compromised build has the reach of an internet client and no more.</p>
<ol><li><strong>Multi-arch is one manifest list</strong>, <code>linux/amd64</code> and <code>linux/arm64</code>, so a</li></ol>
<p> single tag serves an amd64 cluster node and an arm64 developer machine without emulation.</p>
<h3>Kubernetes Pull Configuration</h3>
<p>Kubernetes pulls from <code>oci.hanzo.ai</code>, with the pull identity supplied as an <code>imagePullSecret</code> synced from KMS. Without a credential the kubelet asks anonymously and the pull fails in a way that reads as a missing image rather than a missing credential, so the secret is not optional:</p>
<pre><code class="lang-yaml"># K8s deployment spec
apiVersion: apps/v1
kind: Deployment
metadata:
name: iam
namespace: hanzo
spec:
template:
spec:
containers:
- name: iam
image: ghcr.io/hanzoai/iam:latest
imagePullPolicy: Always
imagePullSecrets:
- name: ghcr-pull-secret</code></pre>
<p>For tagged releases, the pull policy changes:</p>
<pre><code class="lang-yaml"># Tagged release - no need to re-pull
image: ghcr.io/hanzoai/iam:1.584.0
imagePullPolicy: IfNotPresent</code></pre>
<h3>In-Cluster Registry as Pull-Through Cache</h3>
<p>The self-hosted registry runs as a Kubernetes deployment with pull-through proxy configuration:</p>
<pre><code class="lang-yaml"># registry config.yml
version: 0.1
proxy:
remoteurl: https://ghcr.io
username: $GHCR_PULL_USER
password: $GHCR_PULL_TOKEN
storage:
filesystem:
rootdirectory: /var/lib/registry
maintenance:
uploadpurging:
enabled: true
age: 24h
interval: 1h
delete:
enabled: true
http:
addr: :5000
headers:
X-Content-Type-Options: [nosniff]</code></pre>
<p>When a node requests an image from <code>localhost:5000</code>, the registry checks its local storage first. On a cache miss, it pulls from GHCR, caches the layers locally, and serves them to the node. Subsequent pulls from any node in the cluster hit the local cache.</p>
<h3>Deployment via CI</h3>
<p>The deploy step uses <code>kubectl set image</code> to trigger a rolling update:</p>
<pre><code class="lang-yaml">deploy:
needs: build
steps:
- name: Deploy
run: |
kubectl set image deployment/iam \
iam=ghcr.io/hanzoai/iam:v1.33.25
kubectl rollout status deployment/iam --timeout=300s
- name: Verify health
run: |
kubectl wait --for=condition=available deployment/iam \
--timeout=120s</code></pre>
<h2>Security</h2>
<h3>Authentication Architecture</h3>
<p>Registry authentication flows through Hanzo IAM. The Docker registry v2 authentication protocol works as follows:</p>
<pre><code>1. Client attempts: docker pull oci.hanzo.ai/hanzoai/myimage
2. Registry returns: 401 with WWW-Authenticate header
3. Client requests token: GET /v1/iam/registry/token?service=oci.hanzo.ai&amp;scope=repository:hanzoai/myimage:pull
(with Basic auth credentials)
4. IAM validates credentials against user database
5. IAM returns signed JWT with access claims
6. Client retries pull with Bearer token
7. Registry validates JWT signature via JWKS endpoint</code></pre>
<p>IAM implements this via <code>GetRegistryToken</code> (see <code>controllers/registry_token.go</code>):</p>
<ul><li>Authenticates user via Basic auth against IAM user database</li><li>Admin users receive all requested actions (pull, push, delete)</li><li>Non-admin users receive pull-only access regardless of request</li><li>Returns a 15-minute RS256-signed JWT with access claims</li><li>Registry verifies tokens via the JWKS endpoint at <code>/v1/iam/registry/jwks</code></li></ul>
<h3>Signing Key Management</h3>
<p>The registry token signing key follows a strict resolution chain:</p>
<ol><li><code>REGISTRY_SIGNING_KEY</code> env var (inline PEM or <code>kms://SECRET_NAME</code> reference)</li><li><code>REGISTRY_SIGNING_KEY_FILE</code> env var (path to PEM file)</li><li><code>REGISTRY_SIGNING_KEY_SECRET</code> env var (KMS secret name, default: <code>IAM_REGISTRY_SIGNING_KEY</code>)</li></ol>
<p>In production (<code>ENVIRONMENT=production</code>), a persistent signing key MUST be configured. The server will panic on startup if KMS key resolution fails. In development, an ephemeral RSA key is generated per process for convenience.</p>
<h3>Credential Sources</h3>
<p>| Operation | Credential | Auth method | |---|---|---| | Push to <code>oci.hanzo.ai</code> | the build&#x27;s IAM machine identity | <code>client_credentials</code> → per-repository registry token | | Pull from <code>oci.hanzo.ai</code> | an <code>imagePullSecret</code> synced from KMS | the same token flow, presented by the kubelet | | Pull an upstream base image | none | anonymous, from wherever it is published |</p>
<p>There is no registry username and no registry password anywhere in that table. The only durable credential is the machine identity, which IAM issues and IAM revokes — one authority, per HIP-0111 — and a build never holds a credential for a registry it does not itself push to.</p>
<p>Rotation therefore happens in one place and takes effect on the next build. No forge settings to edit, no manifests to re-sync, no secret in source.</p>
<h3>Image Signing with Sigstore</h3>
<p>All release images SHOULD be signed using cosign (Sigstore project) for supply chain verification:</p>
<pre><code class="lang-bash"># Sign after push (in CI)
cosign sign --yes \
--oidc-issuer=https://token.actions.githubusercontent.com \
ghcr.io/hanzoai/iam@sha256:${DIGEST}
# Verify before pull (in cluster)
cosign verify \
--certificate-oidc-issuer=https://token.actions.githubusercontent.com \
--certificate-identity-regexp=&quot;github.com/hanzoai/.*&quot; \
ghcr.io/hanzoai/iam@sha256:${DIGEST}</code></pre>
<p>Cosign uses keyless signing with GitHub Actions OIDC identity. No long-lived signing keys to manage. The signature proves that the image was built by a GitHub Actions workflow in the <code>hanzoai</code> organization.</p>
<h3>Vulnerability Scanning</h3>
<p>All images MUST be scanned for known vulnerabilities before deployment:</p>
<pre><code class="lang-yaml"># In CI pipeline
- name: Scan for vulnerabilities
uses: aquasecurity/trivy-action@master
with:
image-ref: ghcr.io/hanzoai/${{ env.SERVICE }}:${{ env.TAG }}
format: sarif
output: trivy-results.sarif
severity: CRITICAL,HIGH
exit-code: 1 # Fail build on CRITICAL/HIGH findings
- name: Upload scan results
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: trivy-results.sarif</code></pre>
<p>Scan policy:</p>
<ul><li><strong>CRITICAL</strong>: Build MUST fail. No exceptions.</li><li><strong>HIGH</strong>: Build MUST fail. Exceptions require security team approval.</li><li><strong>MEDIUM</strong>: Warning. Tracked in issue backlog.</li><li><strong>LOW</strong>: Informational. No action required.</li></ul>
<h3>SBOM Generation</h3>
<p>Software Bill of Materials MUST be generated for all release images:</p>
<pre><code class="lang-bash"># Generate SBOM as OCI artifact
syft ghcr.io/hanzoai/iam:${VERSION} -o spdx-json &gt; sbom.spdx.json
# Attach SBOM to image in registry
cosign attach sbom --sbom sbom.spdx.json \
ghcr.io/hanzoai/iam@sha256:${DIGEST}</code></pre>
<p>The SBOM is stored as an OCI artifact referencing the parent image, using the OCI Referrers API. This allows consumers to discover the SBOM from the image digest without out-of-band communication.</p>
<h2>Operations</h2>
<h3>Monitoring</h3>
<p>The in-cluster registry exposes Prometheus metrics:</p>
<pre><code>registry_storage_blobs_total # Total stored blobs
registry_storage_blobs_size_bytes # Total storage used
registry_http_requests_total # Request count by method/status
registry_http_request_duration_seconds # Request latency histogram</code></pre>
<p>Alert thresholds:</p>
<p>| Metric | Threshold | Action | |---|---|---| | Storage usage | &gt; 80% capacity | Trigger GC, alert on-call | | Pull latency p99 | &gt; 5s | Check network, storage IOPS | | 5xx error rate | &gt; 1% | Page on-call | | Auth failure rate | &gt; 10% | Investigate credential issues |</p>
<h3>Disaster Recovery</h3>
<p>The in-cluster registry is a cache, not a source of truth. If it is lost:</p>
<p>The registry&#x27;s durability is its object store&#x27;s, not the pod&#x27;s: the workload is replaceable and the blobs are not held on its disk. Recovery is redeploying the workload against the same bucket.</p>
<p>What that does not cover is the bucket. The store MUST be backed up on the same terms as any other durable state (HIP-0065), because an image nothing can pull is an outage that no amount of re-running CI shortens — the build that produced a given digest may no longer be reproducible.</p>
<h2>Reference Implementation</h2>
<p>The registry token endpoint in <code>hanzoai/iam</code> is the reference implementation of the authorization half. The build half is <code>hanzoai/ci</code>&#x27;s one reusable workflow (HIP-0036); no repository has a reference workflow of its own to copy, which is the point.</p>
<p>The IAM registry-token handler demonstrates:</p>
<ul><li>Docker registry v2 token authentication</li><li>IAM-backed credential validation</li><li>Role-based access control (admin: push+pull, user: pull-only)</li><li>RSA-signed JWT token generation</li><li>JWKS public key endpoint for token verification</li><li>KMS-backed signing key resolution with ephemeral fallback</li></ul>
<h2>Conformance status</h2>
<p>Measured against the running cluster on 2026-09-09.</p>
<p><strong>GHCR, still the majority pull source.</strong> Every first-party image running in the cluster resolves from GHCR under its own org, and the orgs do not mix: 189 <code>ghcr.io/hanzoai</code>, 73 <code>ghcr.io/luxfi</code>, 13 <code>ghcr.io/zooai</code>. The remainder are upstream base images (<code>python</code>, <code>docker.io/library</code>, <code>rancher/<em></code>, <code>quay.io/jetstack</code>, <code>registry.k8s.io/</em></code>), which is what the standard expects — third-party images are pulled, not published.</p>
<p><strong>Docker Hub, retiring.</strong> <code>hub.docker.com/v2/repositories/hanzoai/{iam,console,commerce}</code> each still return <code>200</code>, so the old mirror&#x27;s tags are still published and still resolvable. Nothing in the cluster runs from <code>docker.io/hanzoai</code>. Those repositories are the residue of the three-tier scheme this revision removes; they are stale from the moment the second push stopped, and the honest fix is to archive them rather than leave tags that look current.</p>
<p><strong><code>oci.hanzo.ai</code>, the target.</strong> <code>oci.hanzo.ai/v2/</code> returns <code>401</code> — an OCI registry demanding a token, not a <code>404</code> from a host that has no registry behind it — and 13 running images resolve from <code>oci.hanzo.ai/hanzoai</code>. The <code>registry:2</code> workload backing it runs in <code>hanzo-build</code> and <code>hanzo</code>.</p>
<p>The token flow in §Authentication is the one that carries the <code>401</code>: a client is sent to <code>/v1/iam/registry/token</code> on IAM, which is the estate&#x27;s <code>/v1/</code> shape and not an <code>/api/</code> path.</p>
<h2>Copyright</h2>
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hip-0033.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>