I personally dont like how we need to specify registry url. Should this be optional/default?
For hypeman run we try internal registry first and docker.io if registry name is not specified?

I agree. also it would be best if "hypeman push .." "hypeman pull ..." "hypeman run ..." are always consistent in whatever the user puts for the image name there. e.g. if I push by some name and that works then I should be able to run by that same name and it's running the image I just pushed

DX Fixes Applied (ac17646)

Addressed the consistency concerns raised by @sjmiller609. Here's what was wrong and what's fixed:

Problem: Push / Run naming mismatch

When you pushed an image via hypeman push alpine:3.19 myapp, the registry stored it as localhost:8081/myapp:latest (with the registry host prefix). But hypeman run myapp normalized the name to docker.io/library/myapp:latest — a completely different key. So push and run couldn't round-trip.

Fixes

1. Strip registry host prefix on push (registry.go)

The registry's manifest PUT handler was prepending req.Host (e.g., localhost:8081) to the repo name before storing. Now it uses just the path component, so Docker's ParseNormalizedNamed handles normalization consistently:

• push myapp → stored as docker.io/library/myapp:latest
• run myapp → looks up docker.io/library/myapp:latest → ✅ found

2. Backward-compat fallback in GetImage (images/manager.go)

Added a fallback: if the normalized name isn't found, also try prepending the internal registry URL. This handles images that were stored with the old localhost:PORT/name format.

3. Build image_ref uses short name (builds/manager.go)

Build results now return image_ref: "mybuiltapp" instead of "localhost:8081/mybuiltapp", so the user can directly hypeman run mybuiltapp with the value from the build output.

4. Registry auth accepts user JWTs (middleware/oapi_auth.go)

hypeman push from the CLI sends a regular user JWT token, but the /v2/ registry endpoints only accepted special registry-scoped tokens. Added a fallback to validate regular user JWTs for registry paths.

5. Regenerated oapi code + added make run target

The image_name field from the OpenAPI spec wasn't in the generated Go code, causing 400 validation errors. Regenerated. Also added a make run target for running without live reload.

Verified DX flow

$ hypeman push alpine:3.19 myapp
Pushed localhost:8081/myapp

$ curl http://localhost:8081/images/myapp
{"name": "docker.io/library/myapp:latest", "status": "ready", ...}

$ hypeman run myapp
Creating instance myapp-6dh6...
diitkynoorkq644o28x06cib   ← works!

Still open

• Build e2e test: hypeman build with image_name accepted the API call correctly, but the builder VM can't pull base images from Docker Hub (network isolation issue unrelated to this PR). The image_ref would return "mybuiltapp" on success.
• CLI build command: Doesn't expose --image-name flag yet — would need a CLI-side change to pass through the new API field.

Build VM Networking Fixed (b2f5d1b)

The build system now works end-to-end. Here's what was broken and what's fixed:

Root cause: builder VMs couldn't reach the host registry

The builder VM was configured with registry_url: "localhost:8081", but inside the VM localhost refers to the VM itself — not the host machine. Three separate issues compounded:

1. Registry URL not reachable — localhost:8081 inside VM = connection refused
2. BuildKit HTTPS mismatch — the baked builder image wrote a buildkitd.toml with https=true, but the registry is HTTP
3. iptables NAT collision — multiple hypeman instances on the same host shared the same hypeman-nat iptables comment, causing them to overwrite each other's MASQUERADE/FORWARD rules. Our instance's rules were getting deleted by other instances' startup.

Fixes

1. Registry URL rewriting for VMs (providers.go)

ProvideBuildManager now rewrites localhost:PORT → GATEWAY_IP:PORT (e.g., 10.101.0.1:8081) using the subnet config. Builder VMs reach the host via the bridge gateway IP.

2. Proper BuildKit config in builder agent (builder_agent/main.go)

Added setupBuildKitConfig() that writes a buildkitd.toml with http=true + insecure=true for the internal registry. Also sets DOCKER_CONFIG=/home/builder/.docker explicitly for rootlesskit user namespace compatibility.

3. Multi-tenant iptables isolation (bridge.go)

Changed iptables comments from generic hypeman-nat to bridge-scoped hypeman-nat-{bridge_name}. Each hypeman instance now manages its own rules without interfering with others.

4. Registry auth path pattern fix (oapi_auth.go)

Fixed registryPathPattern regex to support repository names with 3+ path segments (a/b/c). Addresses bugbot's "deep image paths break build pushes" concern.

5. VM subnet auth fallback (oapi_auth.go)

isInternalVMRequest was hardcoded to 10.102.x.x — now accepts the subnet CIDR as a parameter so it matches the actual configured subnet.

Verified e2e flow

$ curl -X POST localhost:8081/builds -F [email protected] -F image_name=mybuiltapp
{"id": "xjop5eqomak8gkxco2odqnoo", "status": "queued"}

# Build completes in ~3.6s:
$ curl localhost:8081/builds/xjop5eqomak8gkxco2odqnoo
{"status": "ready", "image_ref": "mybuiltapp", "image_digest": "sha256:0f464e..."}

$ hypeman run mybuiltapp
Creating instance mybuiltapp-uzyx...
e6wo9ytjpl5gf3hngurx8w4k  ← works!

Bugbot responses

• "Qualified names no longer round-trip" — False positive. ParseNormalizedNamed handles normalization consistently for both push and run. The backward-compat fallback in GetImage covers legacy images stored with the old prefix.
• "Deep image paths break build pushes" — Valid concern, fixed by updating registryPathPattern to use (.+?)/(manifests|blobs|tags|referrers)/ instead of the old 2-segment limit.

✱ Stainless preview builds

This PR will update the hypeman SDKs with the following commit message.

feat: Add image_name parameter to builds

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-02-15 13:49:39 UTC

Rebased onto main + addressed bugbot comment

Bugbot: "Repo parsing breaks reserved path names"

This is now a non-issue after rebasing. The base branch already switched from a regex to v2.Router() from docker/distribution (introduced in the two-tier cache PR #70), which properly parses all OCI repository names including those with reserved segment names like blobs or manifests. The regex we had (registryPathPattern) no longer exists in the codebase.

Rebase summary

Rebased onto main (which included ~30 commits since our branch point). Key changes integrated:

• Two-tier build cache (feat(builds): implement two-tier build cache with per-repo token scopes #70) — merged ImageName into RepoPermission-based token scoping
• Docker registry token auth (fix: implement proper Docker registry token auth for BuildKit #75) — kept their v2.Router() repo parsing, added our user JWT fallback and subnet CIDR checks on top
• Pre-cache base images via BuildKit mirror (feat: pre-cache base images and serve via BuildKit mirror #91) — kept their setupBuildkitdConfig with TLS/CA cert support, added our multi-dir config writes
• Native overlayfs snapshotter (perf(builds): native overlayfs snapshotter + zstd compression #92) — kept their BUILDKITD_FLAGS env var approach (replaces our simpler DOCKER_CONFIG approach)
• erofs optimization + revert (perf: switch app rootfs from ext4 to erofs with LZ4 compression #94, revert: remove in-VM erofs creation, use host-side umoci extraction #98) — handled drivers.go deletion
• Metadata field (Add metadata field to instances #97) — no conflicts

All conflicts resolved carefully to preserve both sides' functionality. Builds and vets clean.

Bugbot Autofix prepared fixes for 2 of the 2 bugs found in the latest run.

• ✅ Fixed: Build metadata can reference missing custom image
  • Moved imageRef = req.ImageName inside the success branch of ImportLocalImage, so metadata only references the custom image name when re-tagging actually succeeds.
• ✅ Fixed: Custom image readiness check uses wrong reference
  • Changed waitForImageReady call to pass repo:tag instead of just repo, so non-latest tagged custom images are correctly checked for readiness.

Or push these changes by commenting:

@cursor push c3527c7dd6

diff --git a/lib/builds/manager.go b/lib/builds/manager.go
--- a/lib/builds/manager.go
+++ b/lib/builds/manager.go
@@ -622,14 +622,15 @@
 			if tag == "" {
 				tag = "latest"
 			}
-			imageRef = req.ImageName
 			if _, err := m.imageManager.ImportLocalImage(buildCtx, repo, tag, result.ImageDigest); err != nil {
 				m.logger.Warn("failed to re-tag image", "build_id", id, "image_name", req.ImageName, "error", err)
 				// Don't fail the build - the image is still accessible via builds/{id}
 			} else {
 				m.logger.Info("re-tagged build image", "build_id", id, "from", buildRepo, "to", repo)
+				imageRef = req.ImageName
 				// Wait for the re-tagged image to be ready
-				if err := m.waitForImageReady(buildCtx, repo); err != nil {
+				retaggedRef := repo + ":" + tag
+				if err := m.waitForImageReady(buildCtx, retaggedRef); err != nil {
 					m.logger.Warn("re-tagged image conversion timed out", "build_id", id, "image_name", req.ImageName, "error", err)
 				}
 			}