Vercel Container Registry

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

With the Vercel CLI, vercel vcr authenticates your container tool and resolves the full image reference.

VCR also works without the Vercel CLI. It implements the Docker Registry HTTP API v2 with OCI media types, so you can point any OCI tooling such as Docker or Podman at vcr.vercel.com and authenticate, push, and pull yourself. See Use your container tool directly.

You need three things:

• A Vercel project. Every VCR repository belongs to one project, and every vercel vcr command targets one project. Run vercel link in your project directory to link it, or pass --project <name-or-id> to each command.
• Docker, Podman, or Buildah installed and on your PATH. vercel vcr build and vercel vcr push run your local container tool instead of replacing it, so the tool name is always required and its own flags still apply.
• A Dockerfile or Containerfile in the directory you build.

You don't need to create a repository first. VCR creates one on the first push, as long as your account has access to the project.

From your project directory, log in and then build and push in one step:

vercel link
vercel vcr login docker
vercel vcr build docker . --push

vercel vcr login mints a short-lived, project-scoped OpenID Connect (OIDC) token and passes it to your container tool with the username oidc. The credentials are valid for 12 hours, so re-run the command to refresh them.

vercel vcr build tags the image for your project and --push uploads it. With Docker Buildx installed, the CLI builds and pushes in a single step with zstd compression, which is the recommended format for VCR images. Podman and Buildah build first, then push with zstd compression. Without Buildx, Docker builds and pushes without zstd compression, and the CLI warns you.

Replace docker with podman or buildah to use a different tool.

Without extra arguments, the commands above push vcr.vercel.com/<team-slug>/<project-name>/<project-name>:latest:

Pass only a repository name, optionally with a tag. The CLI adds the registry host, team, and project segments, and rejects a name containing /.

Omit --push to build locally, then push when you're ready:

vercel vcr build docker .
vercel vcr push docker

Both commands resolve the same defaults, so push finds the image that build produced. If you passed a name[:tag] to build, pass the same one to push.

Anything after -- goes to the container tool unchanged:

vercel vcr build docker . -- --no-cache --build-arg KEY=value

The CLI doesn't wrap pull. Print the full reference for a tag, then pull that reference with your container tool. tag inspect reports the values to use in place of team-slug and project-name. With the default push, the repository is named after your project, so project-name appears twice in the reference. If you passed a name[:tag] when pushing, use that repository name in the tag inspect command and as the last segment of the reference instead:

vercel vcr tag inspect project-name latest
docker pull vcr.vercel.com/team-slug/project-name/project-name:latest

A full image reference includes the registry host, team slug, project name, repository name, and tag or digest:

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

The team-slug segment is the slug in your dashboard URL, and project-name is the project the repository belongs to. vercel vcr build and vercel vcr push assemble both segments from the linked project, so you only type the repository and tag.

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

Repositories are private by default, but you can share them with specific Vercel teams or make them public.

Pushing creates a repository automatically. To create an empty one 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 run vercel vcr add my-repository.

If you'd rather not use vercel vcr build and vercel vcr push, authenticate and push with your container tool yourself. You still need the team slug and project name for the image reference, and the account you authenticate with still needs access to that project.

Create a token on the Account Tokens page and set VERCEL_TOKEN to that value. The Docker username is the team ID that owns the project:

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

Docker prints Login Succeeded when authentication succeeds.

You can also authenticate with vercel vcr login docker and then run your container tool directly, which avoids managing a long-lived token.

Docker only applies zstd compression through the Buildx --output exporter, which builds and pushes in one step. Replace team-slug, project-name, and my-repository with your own values, and leave the remaining settings as they are:

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

Without Buildx, build and push in two steps. This path doesn't set zstd compression:

docker build \
  -t vcr.vercel.com/team-slug/project-name/my-repository:latest \
  .
 
docker push vcr.vercel.com/team-slug/project-name/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.