OCI Registry Integration
Templates travel as OCI artifacts in any OCI registry — the same push/pull/tags/digests/replication workflows that run container images run Sandswap templates. This page is the registry integration: endpoints, authentication, and lifecycle. The artifact format and the template concept are in Templates; building templates is in building/templates.
1. Enabling
The registry is configured on the prov instance (prov sandlot):
sandlot -roles prov \
-oci-registry registry.example.com/sandswap-templates \
-registry-username "$REGISTRY_USER" -registry-password "$REGISTRY_PASS"
or as config keys (provision.oci_registry, provision.registry_* — see Sandlot configuration). Without -oci-registry, the prov instance still serves local templates (layers cache + refs under the templates dir; local template directories are discovered lazily — startup scan plus a rescan on every miss — so dropping one into a scan root needs no restart) — pull/push endpoints just fail. The registry address and its credentials are restart-required.
-oci-registry names the repository (host[:port]/path); a template ref (python-ml:v1) is a tag inside it. OCI tags cannot contain colons, so the ref python-ml:v1 is stored as the tag python-ml-v1.
2. Registry authentication
Five shapes, configured on the prov instance; credential selection and TLS are independent, so they combine:
| Method | Keys / flags | Use case |
|---|---|---|
| Username/Password | provision.registry_username / registry_password | private registry (basic auth) |
| Bearer token | provision.registry_token | OAuth/OIDC token auth |
| TLS client cert | registry_cert + registry_key | mTLS |
| Private CA | registry_ca | server verification against your own CA (combines with basic/token; cert/key/ca apply to any credential) |
| Anonymous | (default) | public registry — nothing configured |
Precedence: basic auth wins over the bearer token when both are set; the TLS material (client pair and/or CA) applies regardless of which credential is selected — the common private-registry shape (basic auth over TLS with a company CA) is one config, not a choice. A cert without its key, or any credential without oci_registry, is refused at startup.
Production requires TLS (or a trusted network path): registry basic auth is transported by the registry’s own TLS — without it the credential is plaintext on the wire. Sandswap verifies the server normally unless registry_ca points at a private CA; the e2e suite runs over plain HTTP only because the registry is on localhost.
3. The template lifecycle
| Step | Endpoint (:3100) | sandctl |
|---|---|---|
| Publish a local template | POST /human/templates/{ref}/push | sandctl api template push <ref> |
| Pull into the storage plane’s local store | POST /human/templates/{ref} | sandctl api template pull <ref> |
| List what’s cached locally | GET /human/templates | sandctl api template list |
| Freeze a running flat SandFS first | POST /human/sandfs/{id}/save-template | sandctl api sandfs save-template |
- Push uploads the template’s layers as an OCI image manifest with the Sandswap artifact type (
application/vnd.sandswap.template.v1+json). - Pull verifies and unpacks into the storage plane’s
layers/cache and writes the ref entry — after whichPOST /human/sandfscan instantiate from the ref immediately. This is the overlay pull; a flat pull ({"mode":"flat"}body) reads only the manifest and records the layer digests — the blobs stream straight into each new SandFS volume at creation time, so nothing is cached for flat. - Creation can pull on demand: a
POST /human/sandfsnaming a ref the store does not have yet auto-pulls it first (when a registry is configured) — the create response’spull_statusreportspulledfor that create andcachedwhen the ref was already local. An explicit pull is only needed to control when the download happens. - Refs are mode-tagged: a ref file records whether the template consumes as
flat(seeded by copy from a local dir, or stream-extracted from the registry’s layer blobs) oroverlay(mounted as the read-only lowerdir). The same registry can hold both. - Every deployment needs the template pulled only once into the shared template store — the registry is the distribution point, the storage plane’s
layers/cache is what mounts actually read (overlay mode). Deployments sharing the templates tree need no pull at all: a template saved on one is already on all of them.
4. Typical flows
Build here, run there: save-template on deployment A (freezes a flat SandFS into A’s store) → push ref to the registry → create a SandFS from ref on deployment B (auto-pull) → serve. Push accepts a mode (sandctl api template push <ref> --mode=flat) — a flat push/pull round-trips flat templates, and a flat SandFS created from a pulled flat ref materializes by streaming the blobs directly into its volume.
Air-gapped / mirrored: point oci_registry at your internal mirror (Harbor, Zot, Distribution); standard registry replication keeps sites in sync — Sandswap templates are ordinary OCI artifacts to all of them.
Public base images: pull from a public registry anonymously, push into your private one as your hardened base.
5. Source map
sandlot/provision/template/manager.go—PullTemplate/PushTemplate/ registry auth (AuthConfig.toClient) /layers/+refs/layoutsandlot/provision/volume/volume.go— auto-pull on SandFS creationsandlot/config/config.go+sandlot/cmd/main.go— theprovision.*keys and the-oci-registry/-registry-*flagsdocs/how-it-works/templates.md— artifact format, local storage layoute2e/oci-registry.sh— the full lifecycle against a real (htpasswd-authenticated) registry, including auto-pull-on-create