> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Container Registry

> Store private container images and OCI artifacts, control access, and automate cleanup.

Container Registry stores images and OCI artifacts in your account and region.
Push and pull with Docker, Podman, or another OCI client. Use the REST API to
manage repositories, policies, encryption, and pull-through cache rules.

São Paulo uses `cr.sa-saopaulo-1.basaltic.cloud` for Docker and OCI clients.
Image references include the account handle:
`cr.sa-saopaulo-1.basaltic.cloud/my-account/api:v1`. The management API uses
`registry.sa-saopaulo-1.basaltic.sh`.
Use the repository's returned `uri` rather than assembling it yourself.

## Repositories, images, and tags

A repository has an immutable name, optional deletion protection, and mutable
or immutable tags. An image digest identifies exact manifest bytes. A tag is a
name pointing to a manifest and can move unless tag immutability prevents it.
Multi-platform manifests, signatures, and other OCI artifacts share this model.

Deleting a tag removes that pointer. Deleting a digest removes its manifest and
all tags pointing to it. Shared layers are deduplicated across repositories in
the same account; deleting an image does not immediately reclaim every byte it
references. Cleanup removes layers that are no longer referenced.

## Authentication

The REST API under `/v1` uses a platform bearer token and `X-Account-Id`, as
explained in [Authentication](/authentication). Container clients use `/v2` and
a separate short-lived registry credential obtained from
`POST /v1/authorization-token`. A registry credential cannot call the control
plane. Its per-repository access is determined by IAM and resource policies.

<CardGroup cols={2}>
  <Card title="Create a repository" href="/registry/create-repository">Choose a name, tag settings, and deletion protection.</Card>
  <Card title="Push and pull images" href="/registry/images">Authenticate a container client and deploy by digest.</Card>
  <Card title="Lifecycle policies" href="/registry/lifecycle">Preview cleanup rules before installing them.</Card>
  <Card title="Encryption" href="/registry/encryption">Choose platform encryption or a customer-managed KMS key.</Card>
  <Card title="Pull-through cache" href="/registry/pull-through-cache">Cache upstream images under an account-owned prefix.</Card>
  <Card title="Permissions" href="/registry/permissions">Separate image consumers, publishers, and administrators.</Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.