Vercel Container Registry

Vercel Container Registry (VCR) is a Docker-compatible container registry built into Vercel. Use VCR to store, push, and pull the Docker images you build from a Dockerfile or Containerfile, then run them on Vercel Functions or use them as custom Vercel Sandbox images.

VCR uses the Docker Registry HTTP API v2 using the OCI format. You can use Docker-compatible tooling to authenticate, push images, and pull images from vcr.vercel.com.

A VCR repository belongs to a Vercel project. A full image reference includes the registry host, team slug, project slug, repository name, and tag or digest:

vcr.vercel.com/team-slug/project-slug/my-repository:latest

Repository names can include lowercase letters, numbers, periods, underscores, and dashes. The name can't start or end with a period, underscore, or dash.

Create a VCR repository from your project dashboard:

1. Open Images in your project dashboard.
2. Click Create Repository.
3. Enter a repository name, such as my-repository.

You can also push to a new repository path with Docker-compatible tooling. VCR creates the repository automatically when your authenticated account has access to the project.

The recommended way to authenticate is with OpenID Connect (OIDC) through the Vercel CLI. In a linked project, vercel vcr login authenticates a container tool with VCR. It supports Docker, Podman, and Buildah:

vercel link
vercel vcr login docker

Vercel mints a short-lived, project-scoped OIDC token and passes it to the container tool with the username oidc. The credentials are valid for 12 hours. Re-run the command to refresh them. Use --project to authenticate a different project.

Or create a Vercel token from the Account Tokens page, then set VERCEL_TOKEN to that value:

printf '%s' "$VERCEL_TOKEN" | docker login vcr.vercel.com \
  --username "$VERCEL_TEAM_ID" \
  --password-stdin

For token authentication, the Docker username is the team ID that owns the project.

Docker prints Login Succeeded when authentication succeeds:

Login Succeeded

To use zstd compression, build and push the image with Docker Buildx:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --output "type=image,name=vcr.vercel.com/team-slug/project-slug/my-repository:latest,push=true,oci-mediatypes=true,compression=zstd,compression-level=3,force-compression=true" \
  .

If Docker Buildx is unavailable, you can build and push the image with Docker. This command does not set zstd compression:

docker build \
  -t vcr.vercel.com/team-slug/project-slug/my-repository:latest \
  .
 
docker push vcr.vercel.com/team-slug/project-slug/my-repository:latest

Pull a VCR image with the same full repository path:

docker pull vcr.vercel.com/team-slug/project-slug/my-repository:latest

Use the vercel vcr command group in the Vercel CLI to list, inspect, create, and delete repositories, and to manage their tags and images. For all commands, subcommands, and options, see the Container Registry CLI Reference.

For VCR storage costs, size limits, plan limits, and compatibility limits, see Limits and Pricing.

Several Vercel products can use VCR images for product-specific workflows:

• Vercel Sandbox can create sandboxes from custom VCR images. See Sandbox Images for more information.
• Vercel Functions can run custom VCR images. See container images usage for more information.