Container Registry

Vetrix includes a built-in OCI Distribution Specification v1.1 container registry. Every repository automatically has a registry namespace at the same owner/repo path.

Prerequisites

The registry surface (/v2/* and the per-language package surfaces below it) is only mounted when the operator has wired the on-disk blob root. The boot path enforces a fail-stop on this:

VETRIX_BLOB_DIR — absolute path to the registry blob root on a filesystem the server can write to. Setting this enables the OCI v2 endpoint, the package registries (/npm, /pypi, /go), and the registry GC scheduler. Overrides the storage.blob_dir TOML key when both are set. See ../../runbook-docs/storage/registry-volume.md for layout, mode, and backup notes.
VETRIX_REGISTRY_DISABLED=1 — operator opt-out. Setting this keeps the binary booting with the registry surface intentionally off; every registry route returns 404 and the GC scheduler does not start.

The binary refuses to start when VETRIX_BLOB_DIR is unset AND VETRIX_REGISTRY_DISABLED is not set to 1. The error line names both env vars verbatim:

vetrix: VETRIX_BLOB_DIR is unset and VETRIX_REGISTRY_DISABLED is not set;
refusing to start. Set VETRIX_BLOB_DIR to a writable path to enable the
registry, or set VETRIX_REGISTRY_DISABLED=1 to explicitly opt out.

If /v2/ returns 404 page not found on a deployment you expected to have a registry, this is your first thing to check — the route is not mounted because the env vars were not wired.

Endpoint

https://<vetrix-host>/v2/

Authentication

The registry accepts:

Bearer token — supply the same JWT you use for the REST API:
```
Authorization: Bearer <token>
```
Basic auth — use your Vetrix username and JWT token as the password:
```
Authorization: Basic base64(<username>:<token>)
```
This is the format used by docker login.

Public repositories allow unauthenticated pulls. All push operations require authentication. Only the repository owner may push.

Docker CLI usage

# Log in
docker login <vetrix-host> -u <username> -p <jwt-token>

# Push an image
docker tag myapp:latest <vetrix-host>/<owner>/<repo>:latest
docker push <vetrix-host>/<owner>/<repo>:latest

# Pull an image
docker pull <vetrix-host>/<owner>/<repo>:latest

Supported endpoints

Method	Path	Description
`GET`	`/v2/`	API version check
`GET`	`/v2/<name>/tags/list`	List tags for an image
`GET/HEAD`	`/v2/<name>/manifests/<ref>`	Pull manifest by tag or digest
`PUT`	`/v2/<name>/manifests/<ref>`	Push manifest
`DELETE`	`/v2/<name>/manifests/<ref>`	Delete manifest or untag
`GET/HEAD`	`/v2/<name>/blobs/<digest>`	Pull blob
`DELETE`	`/v2/<name>/blobs/<digest>`	Delete blob
`POST`	`/v2/<name>/blobs/uploads/`	Initiate chunked upload
`GET`	`/v2/<name>/blobs/uploads/<uuid>`	Get upload status
`PATCH`	`/v2/<name>/blobs/uploads/<uuid>`	Append chunk
`PUT`	`/v2/<name>/blobs/uploads/<uuid>?digest=`	Finalise upload

Image naming

The <name> component identifies the image within a repository. The canonical form is <owner>/<repo> which uses the repository name as the image name. You can also specify a sub-image: <owner>/<repo>/<image>.

CI/CD integration

To build and publish images from a Vetrix CI pipeline without managing credentials manually, use the bundled vetrix/publish-artifact@v1 action. It handles authentication, tagging, and digest extraction automatically.

See publish-action.md for the full input/output reference, sample pipeline YAML, and troubleshooting guidance.

CLI reference

Operators can manage registry images, tags, storage, and garbage collection directly from the command line using vetrix-cli registry. See ../../admin-docs/registry/admin-cli.md for the full subcommand reference, flag tables, and exit codes.

Error format

Errors follow the OCI Distribution Spec:

{
  "errors": [
    {
      "code": "MANIFEST_UNKNOWN",
      "message": "manifest unknown",
      "detail": null
    }
  ]
}