Anvil includes an OCI-compatible container registry served from the same host as your repositories. You authenticate with a registry token, then push and pull images with Docker, Podman, or any client that speaks the OCI Distribution Specification.

Images are addressed as anvil.fangorn.io/<org>/<repo>:<tag>, for example anvil.fangorn.io/fangorn/anvil:latest. The registry repository is created automatically on the first push.

Authentication

The registry uses the Docker v2 token-auth protocol. A client that hits a registry endpoint without credentials receives a 401 with this header:

WWW-Authenticate: Bearer realm="https://anvil.fangorn.io/v2/auth",service="anvil.fangorn.io"

The client then exchanges Basic Auth credentials at /v2/auth for a JWT (valid 300 seconds) and retries the original request with Authorization: Bearer <jwt>. Docker handles this exchange for you after docker login.

You can authenticate with one of three credential types as the Docker password:

Create a registry token

Registry tokens are separate from your account password and from API personal access tokens. Create one at Settings -> Registry Tokens (https://anvil.fangorn.io/users/settings/registry-tokens).

Each token has:

The plaintext token is shown only once, at creation time. It is prefixed with anvreg_. Copy it immediately; Anvil stores only a SHA-256 hash and cannot show it again.

Scope format

A scope is <action>:<org>/<repo>, where <action> is pull, push, or delete. The repository part may be a single name or * to match every repository in the org. Enter multiple scopes as a comma-separated list.

A token grants only the intersection of its scopes and your account’s permissions on each repository. Pushing to a repository that does not yet exist is permitted if your account can create repositories in the org; the registry repository is auto-created as private on first push.

Log in with Docker

Use your Anvil username and the registry token as the password:

docker login anvil.fangorn.io \
  --username your-anvil-username \
  --password <your-registry-token>

For automation, pass the token on stdin so it does not appear in shell history or process listings:

echo "$ANVIL_REGISTRY_TOKEN" | docker login anvil.fangorn.io \
  --username your-anvil-username --password-stdin

Push an image

Tag the image with the registry host, org, and repository, then push:

docker tag myapp:latest anvil.fangorn.io/fangorn/anvil:latest
docker push anvil.fangorn.io/fangorn/anvil:latest

The push uploads blobs (layers and config) followed by the manifest. Anvil verifies each blob digest against its content and rejects a manifest whose media type is not a supported OCI or Docker manifest type.

A tag reference must match ^[a-zA-Z0-9_][a-zA-Z0-9._\-]{0,127}$, or be a sha256: digest. Manifests can also be pushed by digest.

Pull an image

docker pull anvil.fangorn.io/fangorn/anvil:latest

Pulls from a public registry repository do not require authentication. Pulls from a private repository require a token with a matching pull: scope.

CI integration

Anvil CI runners inject registry credentials into every job environment and run docker login for you before pulling any image hosted on the Anvil registry. You do not add a docker login step to your pipeline.

The credentials and the values you reference in image tags come from these environment variables, set by the runner:

The CI token grants pull and push only on the repository the job is building. To push to a different repository, supply your own registry token as a CI secret and run docker login against it.

The following .anvil.yml builds the image, pushes it tagged with the commit SHA, then tags and pushes latest:

steps:
  - name: build-and-push
    run: |
      docker build -t $ANVIL_REGISTRY/$ANVIL_REPO_FULL_NAME:$ANVIL_COMMIT_SHA .
      docker push $ANVIL_REGISTRY/$ANVIL_REPO_FULL_NAME:$ANVIL_COMMIT_SHA

  - name: tag-latest
    run: |
      docker tag $ANVIL_REGISTRY/$ANVIL_REPO_FULL_NAME:$ANVIL_COMMIT_SHA \
                 $ANVIL_REGISTRY/$ANVIL_REPO_FULL_NAME:latest
      docker push $ANVIL_REGISTRY/$ANVIL_REPO_FULL_NAME:latest
    depends_on: [build-and-push]

For more on jobs, dependencies, and runner selection, see .anvil.yml and runners.

Manage packages

The web UI surfaces the images stored for an org and per repository, and lets org owners and admins control visibility, storage limits, and retention.

View an org’s packages

The org packages page (https://anvil.fangorn.io/fangorn/packages) lists every registry repository in the org and shows total storage used, repository count, and manifest count.

Repository visibility

Each registry repository is private or public. Toggle it on the repository’s package settings page (https://anvil.fangorn.io/<org>/<repo>/packages/settings). Public repositories allow anonymous pulls; private repositories require a token with a pull: scope.

Storage quotas

An org owner or admin can set a storage quota for the org under Storage Settings on the org packages page. Enter the limit in GB; clear it to allow unlimited storage. When a push would exceed the quota, Anvil rejects the manifest with 413 and the error code DENIED.

Retention policies

Retention policies prune old images automatically. Create them on a repository’s package settings page. A policy must set at least one of the following, and may combine them:

Both values must be greater than zero when set. A policy is enabled when created and can be deleted from the same page. Anvil applies enabled policies on a schedule and reclaims the underlying blob storage once a blob is no longer referenced by any manifest.

Delete images

From a repository’s package settings page you can select tags and delete them, or delete a manifest by digest. Deletion is also available over the OCI API to a token with a delete: scope — see the API reference.

Manage your tokens

Registry tokens are scoped per user and listed at Settings -> Registry Tokens. The list shows each token’s name, prefix, scopes, expiration, and the date it was last used. Revoke a compromised token by deleting it; it stops working immediately.

Troubleshooting

OCI Distribution API reference

All endpoints are served under /v2. Reads require a token with a pull scope (or none for public repositories); writes require push; deletes require delete. Error responses are JSON of the form {"errors": [{"code": "...", "message": "..."}]}.

Catalog and tag pagination

/v2/_catalog and /v2/<org>/<name>/tags/list accept n (page size) and last (the final item of the previous page). When more results exist, Anvil returns a Link header with rel="next":

Link: </v2/_catalog?n=100&last=fangorn/anvil>; rel="next"

Related pages

• .anvil.yml — pipeline and step syntax for build jobs
• Runners — self-hosted runners that build and push images
• CLI reference — managing repositories and tokens from the terminal
• Webhooks — events emitted by the registry
• Get started — set up your first repository