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 linkvercel vcrlogindocker

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 loginvcr.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 buildxbuild \--platformlinux/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 \-tvcr.vercel.com/team-slug/project-slug/my-repository:latest \.docker pushvcr.vercel.com/team-slug/project-slug/my-repository:latest

Pull a VCR image with the same full repository path:

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

Share a repository with other Vercel teams to give them read access to its images. Sharing applies to the whole repository, including all of its tags and images.

Repositories belong to a single project. To use a repository's images from other projects in your team, share the repository with your own team.

To share a repository from your project dashboard:

1. Open Images in your project dashboard and select the repository.
2. Open the Settings tab.
3. Under Repository Sharing, enter the team ID or slug of the team you want to share with, then click Add Team.

You can share a repository with up to 100 teams. To revoke access, remove the team from the same section.

You can also manage sharing from the CLI with vercel vcr permissions:

# Share a repository with a teamvercel vcrpermissionsmy-repositoryaddother-team# List teams with accessvercel vcrpermissionsmy-repositoryls# Revoke a team's accessvercel vcrpermissionsmy-repositoryrmother-team

Teams with access can pull images and use them in Vercel Sandbox. They can't push images, delete images, or share the repository with other teams.

A team with access pulls a shared image with its full repository path after authenticating as their own team:

docker pullvcr.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, to manage their tags and images, and to manage repository sharing. 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.