Container Registries
Flow steps that run containers (container.run, ansible.playbook, tf.plan, tf.apply) pull their images from container registries, and container.build pulls the base images it builds on. Public images need nothing. Images in a registry that needs a login — a private package on ghcr.io, a Docker Hub account, a company registry — pull with a registry credential: a login an organization admin stores once, which the platform hands to every container step in the organization whose image lives on that registry. The flow itself does not change.
A deployment can also run the platform registry, Hegemony's own container registry on the object store. Container steps then keep copies of the images they pull in it and pull the copies on later runs, so an upstream registry's rate limits, speed or outages stop mattering, and a site can be prepared to run offline. Nobody logs in to it: steps get access on their own, for their own organization. See The platform registry.
What a Registry Credential Is
A registry credential belongs to one organization and holds:
- Registry host — the registry as it appears in image references, with an optional port:
ghcr.io,registry.example.com:5000. Docker Hub is stored asdocker.io; its other spellings (index.docker.io,registry-1.docker.io) are normalized to it, and the platform writes it under the key Docker expects (https://index.docker.io/v1/). - Username — the registry login name (for GitHub Container Registry, the GitHub user name; for a robot account, its name).
- Password reference — the password or token as a secret reference,
{{ secret('scheme://path/key') }}. Plaintext values and the platform-onlyenv()andfile()helpers are refused, as for file repositories: the value never enters the database, and it resolves in the organization's own secret namespace (orgs/<slug>/…) when a step uses it. - An optional description.
There is one credential per registry host per organization. Docker picks the login by host, so a second row for the same host could never be used.
Credentials are managed in Settings → Registry Credentials (organization admins; everyone with viewer can see them) and through the API under /registry-credentials. Rows of the designated shared organization are visible to other organizations read-only, with the password reference hidden; a consumer organization's steps use their own organization's credentials, never the shared organization's.
How Steps Use It
Before a container-backed step runs, the worker fetches the run organization's credentials (references only), resolves each reference in the run's organization, and writes a private Docker configuration (config.json) that lives only for that step. The container runner points DOCKER_CONFIG at it, so both ways it pulls — the Docker Engine API with its X-Registry-Auth header, and the docker pull fallback — present the login for the image's host. Every host the organization has a credential for is written, whichever image the step ends up pulling (handler defaults fill in the image after the flow is read). The directory is removed when the step ends.
The resolved password and its base64 user:password form join the step's redaction set, so neither appears in run events, evidence or step output.
A container.build step gets the same file: an image it pushes to a registry other than the platform's goes there with the organization's credential for that host (see Building Images).
What happens when something is missing:
- No credential for the image's host: the pull runs anonymously, as it did before credentials existed.
- A credential whose reference does not resolve: the step emits a warning event naming the host and skips that host; the step fails only if the pull then needs that login.
- The internal API cannot be reached: every pull of that step runs anonymously, with a warning event.
Logins that an enabled extension grants the step (the platform registry's, say) go into the same file, and replace an organization credential for the same host. When two extensions grant access to one host, the first in id order is used there, its login with its image cache and build target, and the step's log says which one was left out.
The step's evidence records the image it was given and the registry digest of the image it pulled (image_digest), as the step's own pull reported it. The container runs by that digest, so the record names exactly the content that ran, even when the tag moves or another step pulls the same tag at the same moment. tf.plan, tf.apply and ansible.playbook also put it in their metrics. An image built on the sandbox daemon and never pushed has no digest and runs by its tag. The run's Events tab shows the same for every container step: Running the image by digest: <repository>@sha256:…, or that the image runs by tag.
Testing a Login
Test login on a credential's page logs in to the registry from the API the way docker login does: it asks the registry's /v2/ endpoint, follows its Basic or Bearer challenge (fetching a token from the challenge's realm with the credentials), and reports ok, or an error_kind of auth, network, endpoint_invalid or unknown. A successful test stamps the credential's last-tested time. The test refuses registry hosts that resolve to private or loopback addresses, because the API would be making the request itself (the same guard file imports use); steps on the sandbox can still use such a registry.
Configuration Exchange
Credentials travel in the registry_credentials section of a bundle (host, username, password reference, description), and a platform sync export writes them under registry_credentials/<host>.yaml, keyed by host. The reference travels verbatim; an import enforces the same rules as the API, so a bundle cannot smuggle in a plaintext password.
Building Images
The container.build step builds an image from a Dockerfile among the flow's attachments, on the sandbox. Where the image goes depends on its name:
- A name without a registry, such as
tools/netbox-sync, is the organization's:registry.hegemony.internal/orgs/<org slug>/tools/netbox-sync(the host isHEGEMONY_REGISTRY_HOST). With the platform registry the step pushes it there, and any later step on any worker can run it. Without one the image stays in the sandbox under that name and nothing is pushed: steps that use the sandbox's images directly (docker runor containerlab inside a step) can run it, but acontainer.runstep cannot, since it always pulls its image, and neither can a later build'sFROM, since builds always pull their base images. - A name with its registry in front, such as
ghcr.io/acme/netbox-sync(Docker Hub isdocker.io/...), is pushed to that registry with the organization's registry credential for that host, or without a login when there is none. This needs an open egress policy (see Network below): the sandbox daemon does the push, outside the policy the step's containers are held to. Once the push is done, or has failed, the image's names are taken off the sandbox, which every organization shares. The platform registry is never named this way, with or without its default port: its images take the short name.
Inputs. Image name (as above), extra tags, the build context folder among the flow's attachments (the same files tf.plan and ansible.playbook read, brought from the repository for a flow synced from git), the Dockerfile's path in that folder (default Dockerfile), build arguments, build secrets (an id and a secret reference each), a target stage, a platform and labels. The context holds text files only, as attachments do, and without executable bits (COPY --chmod=0755 for scripts).
Names, tags and output. Every build is tagged run-<short run id> plus the extra tags (a tag that exists moves to the new image). A name is a lowercase OCI name without a tag; a short name's first segment does not look like a host, since that shape is the cache's. The image carries the labels org.opencontainers.image.created, sh.hegemony.run (the run id) and sh.hegemony.step (the step id). The step's output holds steps.<id>.output.reference: for a pushed image, the reference by digest, so a later step runs exactly that image; for an image kept in the sandbox, the run tag, since no registry knows a digest for it. output.destination says where it went (platform, remote or local). The evidence records every reference and the digest, next to the build log.
Network. The build's RUN instructions reach the network only when the step's egress policy is open (open mode, no deny rules); under any other policy they run with no network at all, since a build cannot be held to allow rules, and the step may not push to a registry other than the platform's. Base images (FROM) and ADD URLs are fetched by the sandbox daemon itself, outside the policy, as every container step's image is.
Base images. With the platform registry, the step's Cache base images option (on by default) builds on the organization's copies of its base images, the way Cache image serves a container step's image. For each image a FROM line or a COPY --from names, in the stages the build uses, the step asks the image's registry which digest the tag names today, takes the copy of that digest from the organization's cache or from global, and without one pulls it and saves a copy. BuildKit then reads the image from that copy, by digest. With the image's registry unreachable, the last copy under the tag is used. The step's log says where each base image came from, and the build details record it (base_images). Some images are still pulled from their own registry: every base image of a build with a platform set, since a copy holds only the sandbox's own platform; an image a used stage takes with another --platform; an image named through a variable the Dockerfile does not declare before its first FROM; and an image whose name is also a stage's name. The step's handler page has the details.
Secrets. Build secrets reach a RUN --mount=type=secret,id=<id> instruction through BuildKit, from a private file on the worker: never as build arguments (which the image history keeps), never in a layer or on the build's command line. Their values are redacted from the log.
Isolation. The sandbox is shared by every organization, so every build pulls its base images with the step's own logins, from their registries or from copies in the organization's or the global namespace, and never reads the sandbox's build cache: another organization's image or cached build step can never stand in. Every instruction runs on every build. Only the official Dockerfile frontend runs: a # syntax= directive naming another image, and BUILDKIT_* build arguments, are refused. Anything kept in the sandbox can be run by any step that uses the sandbox directly, so keep credentials out of images; build secrets never reach a layer.
Permissions. A build pushes what its flow says, so whoever may edit and run the organization's flows (flow:manage, run:trigger; editors by default) can push and move tags of the organization's own images in the platform registry, including ones an admin placed there, and can push to any registry the organization saved a credential for, as far as that login may push. Save a pull-only login for a registry builds must not push to. Steps that must run one exact image reference it by digest. Deleting stays with image:manage on the Container Images pages. The worker image ships the Docker CLI's buildx plugin for this; a worker without it fails the step and says so.
The Platform Registry
The platform registry is optional. It is an extension the API ships with, and the registry compose overlay runs zot, the registry itself (see Deployment below). The overlay switches the extension on at the API's first start; without the overlay it stays off until a platform admin turns it on in Settings → Extensions. The worker learns the registry from the API with each container step's access. While it is off, everything above still holds and nothing below applies: the Container Images pages are not in the sidebar, and its routes answer 404.
What it holds
Image names in the registry are registry.hegemony.internal/<namespace>/… (the host is HEGEMONY_REGISTRY_HOST):
| Path | What lives there | Who writes it |
|---|---|---|
orgs/<org slug>/<host>/<repository>:<tag> | the organization's cached copies of upstream images, named after the image's own registry and repository (orgs/acme/docker.io/library/alpine:3.20; a registry port is written after an underscore, registry.example.com_5000) | the organization's container steps |
orgs/<org slug>/<image>:<tag> | the organization's own images | build steps (container.build, see Building Images); organization admins (import) |
global/<image>:<tag> | platform-wide images, readable by every organization | platform admins (import) |
global/<host>/<repository>:<tag> | pre-loaded copies of upstream images, readable by every organization | nothing in the platform yet: the import refuses names that start with a host |
The slugs orgs, global, cache and mirror are reserved for these paths and cannot name an organization. A step reads its own organization's paths, the designated shared organization's, and global; it writes only under its own orgs/<slug>/<host>/…, and a build step also under its own orgs/<slug>/<image>. Nothing one organization caches or builds is served to another, except the designated shared organization's images, which every organization's steps may pull.
A cache path's host segment carries a dot (docker.io, registry.example.com_5000 with the port after an underscore) or is localhost, with or without such a port; nothing else is one. The shape is reserved: an organization's or the global namespace's own image names never start with such a segment: the build step and the import refuse them. An image from a registry whose name has no dot and is not localhost (myregistry:5000) is pulled from it and never cached.
Cache image
Every container-backed step has a Cache image option, on by default. With the platform registry running, the step:
- asks the image's own registry which digest the tag points at today (one
HEADrequest, which Docker Hub does not count against its pull limits); a digest-qualified reference (image@sha256:…) needs no question; - pulls the copy from its organization's cache, or from
global, when one holds that digest; - otherwise pulls from the image's registry and saves a copy, under the tag and under
sha256_<upstream digest>, the key the next run looks up.
If the image's registry cannot be reached, the step runs the newest copy under the tag and says so in a warning event. If the platform registry cannot be reached, the step pulls from the image's registry without caching, with a note. A copy that cannot be pulled falls back to the image's registry. Saving a copy never fails a step: a refused or slow push leaves a note and the step runs the image it already has. Private images are cached too, in the organization's own namespace, pulled with the organization's registry credential. Turn the option off for an image that must always come straight from its registry. container.build does the same for the images it builds on, with its Cache base images option (see Building Images).
The step's evidence records the reference the container ran by (image_served), where it came from (image_source: upstream, cache or platform) and whether this run saved a copy (image_cached). A step served from the cache records the copy's digest; tf.apply pulls the one its tf.plan recorded from the platform registry.
How steps are let in
Before a container step runs, the worker asks the API for the step's access (POST /internal/runs/{run_id}/step-access), which includes a short-lived registry token for the step, and writes it into the same per-step Docker configuration as the registry credentials, under the registry's host. The token acts for the run's organization, is revoked when the step ends, and stops working at most HEGEMONY_RUN_TOKEN_END_GRACE_SECONDS (600 by default) after the run ends. A bearer token the step already fetched with it (below) keeps working until it expires, at most five minutes later. The registry itself (zot) takes only bearer tokens signed by the API, in the handshake every Docker client knows: a request without one gets a 401 that names the API's token endpoint (GET /registry/token) and the scope the request needs, the client fetches a token there with its run token as the HTTP Basic password, and repeats the request with it. The API signs into the token the part of the requested scopes the step is entitled to: pulls from the paths above, pushes only into its organization's cache, never a delete, never the registry's catalog. zot verifies the signature with the public key the API writes for it at startup and checks the token's access against every request; what the token leaves out, zot refuses with a fresh challenge (a 401, which the Docker client reports as denied). Nothing sits between the sandbox daemon and the registry, and no secret is shared with another process: the signing key (HEGEMONY_REGISTRY_TOKEN_KEY) is the API's alone. Through the UI the token endpoint does not exist, and Settings → Platform Configuration says only whether the key is set, never its value.
A step that builds an image asks for the token with the build scope ("builds_images": true in its access request; the run token's scope is registry:build:<slug> instead of registry:step:<slug>). It gets everything above plus push on the organization's own image names, orgs/<slug>/<image> whose first segment does not look like a host; still never a delete, never the catalog, never another organization or global.
A daily cleanup deletes cached copies nobody used for a while and old build tags, by the rules platform admins set on the Retention page; organization and global images otherwise are never deleted automatically (see Retention).
Operations
The registry is zot with the S3 storage driver, storing in the bucket HEGEMONY_REGISTRY_BUCKET under the platform's S3 key. The API creates that bucket at startup: with the internal object store's buckets, or on its own with an external object store, where the platform's S3 key needs the right to create a bucket (or the bucket is created beforehand). zot's local metadata is a rebuildable index of the bucket, not the images; the bucket is backed up with the rest of the object store.
zot has no web page here (a page cannot log in with bearer tokens); the Container Images pages above are the way to browse and delete. For a look at the registry by hand, the API signs an operator a short-lived token with the same key. From the Docker host, through the launcher that knows the stack's compose files (compose:dev:exec for a dev stack):
token=$(task compose:prod:exec -- api \
python -m hegemony_registry.services.registry_tokens --scope 'repository::pull')
task compose:prod:exec -- api \
curl -fsS -H "Authorization: Bearer $token" http://registry.hegemony.internal/v2/_catalogrepository::pull reads the catalog; repository::push the search extension, which is a POST (zot takes the action from the method); repository:orgs/<slug>/<path>:pull,delete reaches one repository. The token lasts five minutes (--ttl for another span) and is an admin's: whoever holds it reads or deletes whatever its scopes name. Images move in and out as archives through the pages (below), and build steps push their own (Building Images).
Container Images pages
Artifacts → Container Images lists the namespaces visible from the active organization: the organization's own (its images and the copies its steps cached), the shared organization's and the global one, each with its repository count and size. A namespace opens its repositories, each with its origin (a cached copy names the upstream it was copied from, read from its path), tag count, size, last update and pull count. A repository opens its tags, each with its digest, platforms, size, push time, last pull and pull count; steps pull a tag as registry.hegemony.internal/<namespace>/<path>:<tag>. Tables show a digest, and a key tag, by its start and end: hover over it to see it whole, or use the copy button next to it. The pages are the extension's, described as data and drawn by the web app. A cached copy carries two tags for one image: the human one and the key tag named after the upstream digest (sha256_…), which the cache looks up. The key tag has an underscore because sha256-<digest> is the shape the OCI distribution spec reserves for referrers fallback tags: zot keeps such tags out of its index and pull statistics, which would hide the copy from these pages and from the cleanup, and keep it forever.
Every size on these pages is what the registry stores, that is the bucket usage: the compressed layers plus the manifest and the configuration. A step's log reports the unpacked size of the same image on the sandbox daemon, typically two to four times larger. The two never match; neither is wrong.
Who sees and deletes what follows the namespaces:
| Namespace | Browse | Delete tags and repositories |
|---|---|---|
| The active organization's | image:view (every member) | image:manage (organization admins) |
| The shared organization's | every organization's members | its own admins, from within that organization |
global | every organization's members | platform admins (image:manage_global) |
Deleting a tag removes that tag alone; the image stays while another tag points at it (a cached copy keeps its key tag until that is deleted too). Deleting a repository removes every image in it. A step that pulled a deleted copy pulls from upstream again and caches it anew. Every delete is an audit entry. Platform admins also see Usage by namespace: every organization's and the global namespace's repository count and size, as zot counts them.
The pages read zot with tokens the API signs for itself, carrying the two scopes no step is ever granted: the catalog and search paths, and a delete. They reach zot by HEGEMONY_REGISTRY_URL (or HEGEMONY_REGISTRY_BACKEND_URL, for a registry the API reaches by another address). Repositories without a tagged image (everything deleted, not yet garbage-collected) are not listed.
Retention
A cleanup runs once a day and deletes what the retention rules say has had its time. Artifacts → Container Images → Retention shows the rules to everyone who may browse images, with the last cleanup's result (images and tags deleted, at most how much it freed, deletes the registry refused) and when the next one is due. Platform admins change the rules (Edit rules), see what the next cleanup would delete (Preview), and run it at once (Run now: it starts at the next maintenance tick, within HEGEMONY_MAINTENANCE_TICK_INTERVAL_SECONDS).
The rules apply to every namespace:
| Images | Rule | Default |
|---|---|---|
Cached copies (orgs/<slug>/<host>/…, global/<host>/…) | A copy nobody pulled or pushed for this many days is deleted, with its tags. The newest copies of each image, by last use, always stay. | 30 days, newest 1 kept |
Build tags: the run-<id> tag container.build gives every image it pushes | A run tag pushed more than this many days ago is deleted. An image goes with its last tag; one that also has a tag people set (latest, v1.2) stays under it. The newest run tags of each image always stay. | 30 days, newest 10 kept |
Every other image of an organization or of global | Never deleted automatically. |
A number of days of 0 means never; a count of 0 keeps none regardless. The starting value for cached copies comes from HEGEMONY_REGISTRY_CACHE_RETENTION (a duration such as 720h) until a platform admin saves the page; the saved rules win from then on.
Whatever the rules say, the cleanup keeps:
- an image a run that has not finished still names in a step's result, by digest: the image a
tf.planwaiting for approval recorded, which itstf.applypulls, say; - an image something pulled within the last day: a step still running names its image only once it finishes;
- a copy or tag the registry has no push or pull time for.
The cleanup deletes tags, never an image by its digest. Just before it deletes in a repository, it reads that repository and the unfinished runs again and deletes only the tags the rules still remove, so a tag added, a pull or a run since its scan keeps the image. An image left without tags stays readable by its digest until zot's next garbage collection (daily) removes it.
Keeping the newest copy of each image matters for a site that loses its upstream registry: a step then runs the newest copy under its tag (see Cache image). A step that finds its copy deleted pulls from upstream again and saves a new one.
Each cleanup records one audit entry per repository it deleted from (entity.deleted, reason retention, with the tags and digests), in the organization's audit log for its own namespace. Saving the rules and Run now are audit entries too (container_image_retention). The cleanup is the registry extension's maintenance job registry:image_retention, listed with the platform's own under Settings → Maintenance Jobs. Deleting an image frees its layers only where no other image uses them, so the bytes reported are an upper bound; zot's garbage collection frees the space within a day.
Image import and export
Images move in and out of the registry as OCI image layout archives: the .tar file docker save writes on Docker 25 and later, and that skopeo copy … oci-archive:<file> reads and writes. docker load -i <file> reads an exported archive back, under the name steps pull it by (registry.hegemony.internal/<namespace>/<path>:<tag>); for a single-platform image the archive also carries Docker's own manifest.json, so daemons older than Docker 25 load it too. One archive holds one image.
Blobs and manifests are named by SHA-256 or SHA-512 digests. An image may have at most 1,000 manifests and indexes, of at most 4 MiB each and 16 MiB together; a larger one is refused, as the API holds them in memory while the image moves.
Export. On a repository's page, Download on a tag streams the archive from the API to the browser, as <path>_<tag>.tar. The browser holds the file until it is saved, so this suits images up to a few gigabytes; a script can stream a larger one to disk (see below). An export is the whole image the tag points at: every platform of a multi-platform image, every layer, cached copies included. Signatures and other artifacts that refer to the image are not part of it.
Import. Import image on a namespace's page (the organization's; global too for platform admins) asks for the name within the namespace, the tag and the archive file, which the browser uploads. An upload may be at most HEGEMONY_REGISTRY_TRANSFER_MAX_UPLOAD_BYTES (1 GiB by default). To take larger archives, raise it on the API and restart the API. The web image passes at most 2 GiB on the upload route, so 2 GiB is the most an upload through the platform's address can be.
The archive is checked before the answer, and anything that is not an OCI image layout is refused with the reason: a compressed archive (decompress it first), a docker save archive from Docker before 25 (convert it with skopeo copy docker-archive:<file> oci-archive:<new file>), or another file. The import then runs in the background: every blob is checked against its digest and size, also the ones the repository already holds (those are not uploaded again), and the manifests follow, an index's platforms before the index. An archive with several images is imported by the tag its index names. Importing under a tag that already exists moves the tag to the imported image, as a push would. When an archive keeps a multi-platform index but only some of its platforms (docker save with Docker's containerd image store does that), the tag points at an index of the platforms present (an index of such indexes is rewritten to match), and the import names the missing ones.
The name follows the registry's naming rules (lowercase letters and digits, parts separated by /), always lands inside the namespace (orgs/<slug>/ or global/ goes before it), and must not start with a part that looks like a registry host (one with a dot, or localhost): that shape is where cached copies live, and the cleanup treats it as such.
A script can do both with an admin's API token (a platform admin's, and the routes under /api/platform/images/, for global):
# Download: streamed to disk.
curl -fsS -H "Authorization: Bearer $HEGEMONY_TOKEN" -o netshoot.tar \
"https://hegemony.example.com/api/images/repository/archive?name=orgs/acme/tools/netshoot&tag=1.0"
# Import: the answer is the queued import.
curl -fsS -X POST -H "Authorization: Bearer $HEGEMONY_TOKEN" \
-H "Content-Type: application/x-tar" -T netshoot.tar \
"https://hegemony.example.com/api/images/transfers/upload?path=tools/netshoot&tag=1.0"Imports. Imports run in the API: Imports, on a namespace's page, shows each with its progress while it runs and its outcome afterwards. An API process runs two at a time; the rest wait as queued. An import the API stopped in the middle of ends failed (at once when the API shuts down, otherwise when it starts again); upload the archive again. An upload is kept in HEGEMONY_REGISTRY_TRANSFER_DIR (the system's temporary directory by default) until its image is pushed, so that directory needs room for the uploads in flight.
| Namespace | Import, download, see its imports |
|---|---|
| The active organization's | image:manage (organization admins) |
global | image:manage_global (platform admins), through the routes under /platform/images |
| The shared organization's | its own admins, from within that organization |
An import is recorded in the audit log as entity.imported on the image when it starts (outcome attempt) and when it ends (success or failure). A download is one entity.exported entry, recorded as it starts. The API reaches the registry with tokens it signs for itself, for the one repository; no Docker daemon is involved.
An air-gapped site. On a connected deployment, let a step cache the image (or import it), then Download it from its repository page. Carry the file to the air-gapped site and use Import image there to upload it into the organization's namespace or global. Steps there pull it as registry.hegemony.internal/<namespace>/<path>:<tag>. For an archive larger than 1 GiB, raise HEGEMONY_REGISTRY_TRANSFER_MAX_UPLOAD_BYTES there first.
Deployment
Add
registrytoSERVICES(next tos3, or with an external S3 endpoint inHEGEMONY_S3_*), setHEGEMONY_REGISTRY_TOKEN_KEY(openssl rand -hex 32) and start the stack.The overlay sets
HEGEMONY_EXTENSIONS_ENABLE=registry, so the API's first start switches Container registry on, as Enable in Settings → Extensions would: it checks the key and makes the registry's bucket (HEGEMONY_REGISTRY_BUCKET). zot starts once the API is healthy, so it finds both. When either is missing, the extension stays off, the API log says why, and the next start tries again. An admin's later switch wins: an extension turned off in Settings stays off across restarts. From then on every API start writes the token public key zot reads.To leave the switch to an admin, set
HEGEMONY_EXTENSIONS_ENABLEto an empty value (or to the extensions you want, withoutregistry). Until the extension is first turned on, zot finds neither its bucket nor its key: it exits, and Docker restarts it about once a minute until then. Once it has been on, zot keeps running even while the extension is off.
The registry listens on no host port: the sandbox daemon and the worker reach it as registry.hegemony.internal on the compose network, over plain HTTP, and the overlay lists that name in the daemon's insecure registries. zot sends clients to the API's token endpoint at HEGEMONY_REGISTRY_TOKEN_REALM (by default the API on the compose network) and reads the token public key from a volume the API writes it into; after a change of the key api is restarted first, then registry. Settings: HEGEMONY_REGISTRY_HOST, HEGEMONY_REGISTRY_URL, HEGEMONY_REGISTRY_BUCKET, HEGEMONY_REGISTRY_IMAGE_TAG (the zot release), HEGEMONY_REGISTRY_S3_SECURE (true when the S3 endpoint is https), HEGEMONY_REGISTRY_CACHE_RETENTION (the Retention page's starting value), HEGEMONY_REGISTRY_BACKEND_URL (where the API reaches zot for the Container Images pages, when that is not HEGEMONY_REGISTRY_URL), and for image import HEGEMONY_REGISTRY_TRANSFER_MAX_UPLOAD_BYTES and HEGEMONY_REGISTRY_TRANSFER_DIR (see Environment Variables). The production hardening guide covers the trust boundaries and multi-host deployments.
Related docs
- Flow step reference — the container handlers, their image fields, the Cache image option and
container.build - Production hardening — the platform registry's trust boundaries
- Secrets Management — reference formats and backends
- File Repository Storage and Connections — the same reference-only credential rule for object storage
- Glossary — Registry Credential