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.
Using the Vercel CLI
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
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 vcrlogindocker
vercel link
Replace docker with podman or buildah to use a different tool.
vercel vcrbuilddocker.--push
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.
What the CLI fills in for you
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.
Value
Pass only a repository name, optionally with a tag. The CLI adds the registry host, team, and project segments, and rejects a name containing /.
Build context
Without extra arguments, the commands above push vcr.vercel.com/
How to override
Default
vercel vcr build docker ./app
.
Repository
Tag
vercel vcr build docker . my-api
The project name
vercel vcr build docker . my-api:1.2.3
--platform linux/arm64
Platform
Project
latest
The linked project
--project my-app
linux/amd64
Build and push as separate steps
Omit --push to build locally, then push when you're ready:
vercel vcrbuilddocker.
vercel vcrpushdocker
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.
Pass flags to your container tool
Anything after -- goes to the container tool unchanged:
vercel vcrbuilddocker.----no-cache--build-argKEY=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 vcrtaginspectproject-namelatest
docker pullvcr.vercel.com/team-slug/project-name/project-name:latest
Image references and repository names
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.
Create a repository
Pushing creates a repository automatically. To create an empty one from your project dashboard:
- Open Images in your project dashboard.
- Click Create Repository.
- Enter a repository name, such as my-repository.
You can also run vercel vcr add my-repository.
Use your container tool directly
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.
To push from a GitHub Actions workflow, use the prebuilt Vercel login action instead. It authenticates with OIDC, so there are no long-lived tokens to manage. See Push Images from GitHub Actions.
Authenticate with a Vercel token
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 loginvcr.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.
Build and push with Docker Buildx
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:
Manage repositories from the CLI
.
--platformlinux/amd64 \
Without Buildx, build and push in two steps. This path doesn't set zstd compression:
docker buildxbuild \
--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"
docker build \
docker pushvcr.vercel.com/team-slug/project-name/my-repository:latest
-tvcr.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.
Previous
Last updated September 4, 2026
Sandbox
Was this helpful?
Next
Cross-link map: Vercel Container Registry (/docs/container-registry)From the Vercel docs graph (built 2026-09-21T05:26:59.511Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.jsonSemantically closest pagesHow to use Vercel Container Registry — Push, store, and pull OCI container images with Vercel Container Registry, then deploy them to Vercel Functions and VercGetting Started — Authenticate your container tool with Vercel Container Registry, then push and pull your first image with the Vercel CLIvercel vcr — Manage Vercel Container Registry from the Vercel CLI: build and push images, manage repositories, tags, and images, andManage Vercel Container Registry with Vercel CLIRunning Docker on Vercel — Learn how to run Docker on Vercel by deploying OCI container images as Vercel Functions, storing them in Vercel ContaineThis page links to (8)Vercel CLI Overview — Learn how to use the Vercel command-line interface \(CLI\) to manage and configure your Vercel Projects from the commandContainer Registry CLI Reference — Use the vercel vcr command group to manage Vercel Container Registry repositories, tags, and images from the command linGetting Started — Authenticate your container tool with Vercel Container Registry, then push and pull your first image with the Vercel CLIPush Images from GitHub Actions — Authenticate GitHub Actions with Vercel Container Registry using OIDC, then build and push images with your container toContainer Registry limits and pricing — Storage pricing, size limits, plan limits, and compatibility limits for Vercel Container Registry.Public and Shared Repositories — Share a Vercel Container Registry repository with specific Vercel teams or make it public for any Vercel team to access.Container Images — Deploy OCI container images with a Dockerfile or Containerfile on Vercel Functions.Images — Start sandboxes from Vercel's Managed Images, or custom OCI images stored in Vercel Container Registry to ship your ownPages that link here (38)By site: vercel-changelog (6) · vercel-kb (20) · vercel-docs (12)From vercel-changelogBring your Dockerfile to Vercel FunctionsIntroducing VCR: Vercel Container RegistryManage Vercel Container Registry with Vercel CLIShare Vercel Container Registry repositories across teamsVercel Container Registry repositories can now be made publicVercel Sandbox now support Custom ImagesFrom vercel-kbDeploy Go apps on Vercel using Docker — Deploy an existing Dockerized Go app to Vercel using Memos as a real-world example, with Neon Postgres for durable data.Deploy a Node.js Fastify app on Vercel with Docker — Build a Node.js application with Fastify and Docker, then deploy it to Vercel Functions. Learn how to configure environmDeploy PHP on Vercel with Docker — Build a PHP application with FrankenPHP and Docker, then deploy it to Vercel Functions with managed configuration, storaDeploy Rust on Vercel with Docker — Build a Rust application with Axum and Docker, then deploy it to Vercel Functions. Learn how to configure environment vaRunning Docker on Vercel — Learn how to run Docker on Vercel by deploying OCI container images as Vercel Functions, storing them in Vercel ContaineRunning Docker on Vercel vs Render — Compare how Vercel and Render run Docker workloads, including deployment model, scaling, image sources, state, and netwoDoes Vercel support Docker deployments? — Vercel supports deploying OCI-compatible container images through Vercel Functions and Vercel Container Registry, with ADeploy ASP.NET Core on Vercel with Docker — Build a .NET application with Docker and deploy it to Vercel Functions. Learn how to configure environment variables, inHow to use Vercel Container Registry — Push, store, and pull OCI container images with Vercel Container Registry, then deploy them to Vercel Functions and VercTranslate Kubernetes manifests to vercel.json — Translate Kubernetes Deployments, Services, Ingress, ConfigMaps, and CronJobs into vercel.json configuration and VercelDeploy Laravel on Vercel with Docker — Build a Laravel application with FrankenPHP and Docker, then deploy it to Vercel with production configuration, externalHow to migrate from Google Cloud Run to Vercel — Migrate from Cloud Run to Vercel by copying your Dockerfile to Dockerfile.vercel, aligning the PORT contract, moving secHow to migrate from Fly.io to Vercel — Move a containerized app from Fly.io to Vercel. Map fly.toml to Dockerfile.vercel and vercel.json, replace Machines withHow to migrate from GHCR to Vercel Container Registry — Migrate container images from GitHub Container Registry \(GHCR\) to Vercel Container Registry \(VCR\), including authent How to migrate from Railway to Vercel — Move an app from Railway to Vercel. Most Railpack-built apps deploy through framework detection with no container; DockeDeploy Symfony on Vercel with Docker — Build a Symfony application with FrankenPHP and Docker, then deploy it to Vercel with production configuration, externalHow to test a container image in Vercel Sandbox before deploying — Validate a container image before deploying by booting it as a custom Sandbox image from Vercel Container Registry \(VCRDeploy Python apps on Vercel using Docker — Deploy a Dockerized Python application that depends on native software, OCR engines, or small local models, plus a Next.Does Vercel support Kubernetes? — Vercel doesn't run Kubernetes clusters. Learn how Kubernetes workloads like Deployments, Ingress, ConfigMaps, and CronJoVercel vs Kubernetes — Compare Vercel and Kubernetes on operational ownership, deployment workflow, scaling, and cost model to decide which plaFrom vercel-docsVercel CLI Overview — Learn how to use the Vercel command-line interface \(CLI\) to manage and configure your Vercel Projects from the commandvercel vcr — Manage Vercel Container Registry from the Vercel CLI: build and push images, manage repositories, tags, and images, andContainer Registry CLI Reference — Use the vercel vcr command group to manage Vercel Container Registry repositories, tags, and images from the command linGetting Started — Authenticate your container tool with Vercel Container Registry, then push and pull your first image with the Vercel CLIContainer Images — Deploy OCI container images with a Dockerfile or Containerfile on Vercel Functions.Runtimes — Runtimes transform your source code into Functions, which are served by our CDN. Learn about the official runtimes suppoProducts — Browse Vercel products for building, deploying, securing, observing, and scaling web applications.Projects overview — A project is where you deploy and operate frontend apps, APIs, backends, containers, and agent workloads on Vercel.Vercel Sandbox — Run untrusted or agent-generated code in isolated Linux microVMs with Vercel Sandbox.Understanding Sandboxes — Learn how Vercel Sandboxes provide on-demand, isolated compute environments for running untrusted code, testing applicatImages — Start sandboxes from Vercel's Managed Images, or custom OCI images stored in Vercel Container Registry to ship your ownHarbor and Terminal-Bench — Run Terminal-Bench and any other Harbor Hub dataset on Vercel Sandbox, with each trial in its own isolated Firecracker m