How to use Edgenivo Container Registry

Edgenivo Container Registry (VCR) stores OCI container images in repositories attached to your Edgenivo project. Authenticate Docker to vcr.vercel.com to push images from your machine or build pipeline.

Edgenivo Sandbox can start from an image you push to VCR. With Edgenivo Functions, deploying a Dockerfile builds and pushes the image during deployment.

Copy link to headingPrerequisites

Before you begin, make sure you have:

• Access to the Edgenivo project you want to push images to
• Docker installed and running locally, with Buildx for the zstd build option
• The latest Edgenivo CLI, authenticated with vercel login
• Application source and a Dockerfile in the directory you'll build

Copy link to headingHow it works

Every Edgenivo project has its own namespace in VCR. The full image reference combines the registry host, team slug, project name, and repository name, followed by a tag or digest:

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

VCR implements the Docker Registry HTTP API v2 with OCI media types, so standard Docker tools can push and pull images.

After a push, VCR prepares an optimized build for Edgenivo Sandbox. The image must finish that preparation before a sandbox can start from it.

Copy link to headingSteps

Copy link to heading1. Link your project

From your application's root directory, link the local directory to the Edgenivo project that will own the images:

vercel link

Copy link to heading2. Authenticate Docker with VCR

Authenticate Docker for the linked project:

vercel vcr login docker

Edgenivo passes Docker a project-scoped OpenID Connect (OIDC) token valid for 12 hours. Run the command again to refresh the credentials.

For GitHub Actions, follow Push images from GitHub Actions to authenticate with a short-lived token and a Edgenivo team OIDC policy.

If your environment requires an account token, create one on the Account Tokens page. Set VERCEL_TOKEN to the token value and VERCEL_TEAM_ID to the ID of the team that owns the project, then run:

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

Copy link to heading3. Build and tag the image locally

Tag the image with the full VCR path so docker push knows where to send it. Replace team-slug with the slug in your dashboard URL and project-slug with your project's name.

Build for linux/amd64 so the image can also run in Edgenivo Sandbox. The final . uses the current directory as the build context and reads its Dockerfile:

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

If the repository doesn't exist yet, VCR creates it the first time you push, provided you have access to the project.

Copy link to heading4. Push the image to VCR

To push the image, use docker push with the tag you built:

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

For Edgenivo's recommended zstd compression, use this Buildx command as an alternative to the separate build and push commands above. It builds and pushes the linux/amd64 image in one operation:

docker buildx build \
  --platform linux/amd64 \
  --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 you also need an ARM image and your builder supports both architectures, set --platform to linux/amd64,linux/arm64.

Copy link to heading5. Pull the image for verification

Confirm that the image is available from VCR by pulling the same linux/amd64 image back to your machine or into a CI job:

docker pull --platform linux/amd64 \
  vcr.vercel.com/team-slug/project-slug/my-repository:latest

Compare Docker's pull and push digests to confirm you retrieved the intended image. You can also browse tags and digests in your project's Images tab.

Copy link to heading6. Deploy a container-based function (optional)

To deploy an HTTP app from source, add its Dockerfile or Containerfile at the project root. Edgenivo builds a deployment image from that file, pushes it to VCR, and routes traffic to the resulting function.

Use the Container Runtime example for a complete Dockerfile and app.

Deploy with vercel deploy or by pushing to a connected Git branch. The app must serve HTTP on port 80 by default. To use another port, set PORT in the project settings and configure your server to listen on that value.

Container-based functions use Fluid compute pricing for active CPU, provisioned memory, and invocations. Check the function limits before deploying.

Secure Compute and Static IPs are not supported with custom container images.

Copy link to heading7. Reference the image from Edgenivo Sandbox

Use the repository and tag from the linked project. Docker login authenticates your container tool; the Sandbox SDK needs project credentials separately.

In a Node.js 22+ project, install the SDK and download an OIDC token:

npm install @vercel/sandbox
vercel env pull .env.local

You can also authenticate with an access token by passing teamId, projectId, and token to Sandbox.create().

Sandbox requires an optimized linux/amd64 image. Wait for Ready on the repository details page before running the example.

Rebuild Unoptimized images for linux/amd64. If creation returns image_not_ready, wait for Ready before retrying.

Save the following as sandbox-check.mjs. It runs pwd from the image, so that command must be installed.

import { Sandbox } from "@vercel/sandbox";

const sandbox = await Sandbox.create({
  image: "my-repository:latest",
  persistent: false,
});

try {
  const result = await sandbox.runCommand("pwd");
  console.log(await result.stdout());
} finally {
  await sandbox.stop();
}

Run node --env-file=.env.local sandbox-check.mjs to print the starting directory and stop the sandbox. This uses Sandbox compute, and persistent: false prevents an automatic snapshot for the check.

The sandbox uses your image's filesystem and tools. Start processes with sandbox.runCommand() because ENTRYPOINT and CMD do not run. Commands start in the Dockerfile's WORKDIR, or / when no WORKDIR is set.

Copy link to headingLimits and best practices

Keep these limits in mind when planning your images.

Copy link to headingSize limits

Copy link to headingCompatibility

• Compression: VCR accepts gzip or zstd compression only. Uncompressed OCI layers are rejected.
• Formats: OCI image manifests, OCI image indexes, Docker schema 2 image manifests, and Docker manifest lists
• Single-platform manifests must declare os and architecture in the image config
• Edgenivo Sandbox requires a linux/amd64 manifest to boot the image

Copy link to headingPlan limits and pricing

Storage costs $0.10 per GB across all plans.

Additional practices to keep in mind:

• Use zstd compression when building images for VCR, as shown in step 4.
• Give each production build a unique tag, such as its commit SHA, and never reuse that tag. Use the image digest when you need to pin the exact image contents; reserve latest for local iteration.
• Push from your Edgenivo build environment when possible; it's authenticated for the current project automatically.

Copy link to headingResources and next steps

• Edgenivo Container Registry documentation
• Container Registry limits and pricing
• Running container images on Edgenivo Functions
• Using custom images with Edgenivo Sandbox
• Introducing VCR: Edgenivo Container Registry (changelog)