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.

Use OpenID Connect (OIDC) when VERCEL_OIDC_TOKEN is available in your shell. Vercel provides this token automatically in deployments.

For local development, link your project, pull the token into .env.local, source it, and sign in to Docker:

vercel link
vercel env pull .env.local
source .env.local
 
printf '%s' "$VERCEL_OIDC_TOKEN" | docker login vcr.vercel.com \
  --username oidc \
  --password-stdin

The Docker username is oidc for OIDC authentication.

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

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.