Running Docker on Edgenivo

Edgenivo supports Docker across your whole workflow. You can deploy an application packaged as an OCI (Open Container Initiative) container image as an autoscaling Edgenivo Function on Fluid compute, store images in Edgenivo Container Registry (VCR), run containers inside Edgenivo Sandbox for testing, and use Docker locally to keep builds reproducible. Each path suits a different stage of building and shipping.

Copy link to headingDeploy a container image as a Edgenivo Function

The main way to run Docker on Edgenivo is to deploy a container image as a Edgenivo Function. Add a Dockerfile or Containerfile to your project root, and Edgenivo builds the image, stores it in VCR, and serves it from a Function that scales automatically with traffic.

The Function scales to zero when idle and uses Fluid compute pricing for active CPU time, provisioned memory, and invocations. CPU billing pauses while your code waits for I/O. The Container runtime is in beta on all plans.

Reach for this when framework detection can't cover your app:

• It depends on a system library such as FFmpeg or Chromium
• It uses a framework Edgenivo doesn't auto-detect yet
• It needs to run exactly as it does elsewhere

Copy link to headingAdd a Dockerfile

When Edgenivo detects no other framework, it builds the Dockerfile at your project root and adds a rewrite that routes all traffic to the resulting image. If project detection matches a framework such as Next.js or Django, that framework wins. To build the Dockerfile instead, run vercel project update --framework container or set "framework": "container" in vercel.json. A Dockerfile.vercel or Containerfile.vercel also works and takes precedence over a detected framework.

Here's a minimal dynamic server using Node.js and the srvx server:

FROM node:26-alpine

RUN npm i -g srvx
WORKDIR /app
COPY server.ts .

# srvx listens on $PORT by default
CMD ["srvx", "--prod"]

export default {
  fetch(req: Request) {
    return Response.json({ ip: req.headers.get("x-forwarded-for") })
  }
}

Static servers work the same way with a Dockerfile that starts with FROM nginx:alpine and copies your static files into /usr/share/nginx/html. Deploy either kind by running vercel deploy or by pushing to a connected Git repository.

Copy link to headingRun multiple services in one project

To deploy more than one application in a single project, define each one as a service and use rewrites in vercel.json to route incoming requests to it. Set each service's entrypoint to its Dockerfile path, relative to the service's root:

{
  "services": {
    "frontend": {
      "root": "frontend/",
      "entrypoint": "Dockerfile.vercel"
    },
    "backend": {
      "root": "backend/",
      "entrypoint": "Dockerfile.vercel"
    }
  },
  "rewrites": [
    { "source": "/api/(.*)", "destination": { "service": "backend" } },
    { "source": "/(.*)", "destination": { "service": "frontend" } }
  ]
}

Copy link to headingKey behaviors

Copy link to headingStore images in Edgenivo Container Registry

Edgenivo Container Registry (VCR) is a project-scoped registry for OCI images, hosted at vcr.vercel.com. It supports the Docker Registry HTTP API v2, so docker push, docker pull, and docker tag work without new tooling. Full image references include the registry host, team slug, project slug, repository name, and tag:

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

Edgenivo provides VERCEL_OIDC_TOKEN automatically in deployments. For local use, install the Edgenivo CLI, Docker, and Docker Buildx, then run these commands from the directory containing your Dockerfile:

vercel link
vercel vcr login docker
vercel vcr build docker . my-repository:latest --push

The CLI authenticates Docker for the linked project, builds the image for linux/amd64, and pushes it to VCR. With Buildx installed, it also applies the recommended zstd compression. If your file is named Dockerfile.vercel, add -- -f Dockerfile.vercel to the build command.

Once an image is in VCR, both Edgenivo Functions and Edgenivo Sandbox can use it. The registry documentation covers authentication, build options, and limits.

Copy link to headingRun Docker with Edgenivo Sandbox

Edgenivo Sandbox gives you an isolated Linux environment for safely running untrusted or user-generated code, and it works with Docker in two ways:

• You can install and run the Docker engine inside a sandbox
• You can boot a sandbox directly from a custom image in VCR

Copy link to headingRun Docker inside a sandbox

Sandboxes can install and run Docker, allowing you to build images and run containers without touching your host system. Each sandbox is a Firecracker microVM with its own kernel and filesystem, and it runs with sudo access, which is what lets you start the Docker daemon inside it.

This is useful for running containerized services like Redis or Postgres as test dependencies, validating an image before you deploy it, or previewing an app served from a container.

Follow the Sandbox quickstart to install the SDK and configure authentication. This example installs Docker in an Ubuntu sandbox, waits for the daemon, and runs Docker's test container:

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

config({ path: ".env.local" });

async function main() {
  const sandbox = await Sandbox.create({
    image: "vercel/sandbox/ubuntu:latest",
    persistent: false,
  });

  try {
    const result = await sandbox.runCommand({
      sudo: true,
      cmd: "bash",
      args: [
        "-euc",
        `
apt-get update
apt-get install -y docker.io
dockerd >/tmp/dockerd.log 2>&1 &
timeout 30s sh -c 'until docker info >/dev/null 2>&1; do sleep 1; done'
docker run --rm hello-world
`,
      ],
      stdout: process.stdout,
      stderr: process.stderr,
    });

    if (result.exitCode !== 0) {
      throw new Error(`Docker setup or test failed: ${result.exitCode}`);
    }
  } finally {
    await sandbox.stop();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run pnpm tsx run-docker.ts. The test container prints a confirmation message before the sandbox stops. sudo: true provides the privileges needed to install Docker and run its daemon.

This example disables persistence for a one-off test. For repeated work, persistent sandboxes retain the Docker installation and pulled images when you resume the same sandbox. Restart the daemon and any containers after resuming; running processes do not survive between sessions.

Containers use their own filesystem and trust store, so they don't inherit the sandbox's proxy CA certificate. The sandbox host already trusts the certificate mounted at /etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem.

When the sandbox firewall terminates HTTPS connections for transform or forwardURL rules, containers must trust that certificate to pass TLS verification. Mount the certificate into the container and update its trust store during the build or when the container starts:

docker run --rm \
  -v /etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem:/usr/local/share/ca-certificates/vercel-proxy-ca.crt:ro \
  my-image \
  sh -c "update-ca-certificates && my-command"

The exact location and trust-update command depend on the base image: use update-ca-certificates on Debian or Ubuntu, and update-ca-trust on Amazon Linux, Fedora, or RHEL. If your app reads a CA bundle from an environment variable instead of the system trust store, point that variable (such as NODE_EXTRA_CA_CERTS) at the mounted certificate path inside the container.

Copy link to headingBoot a sandbox from a custom image

To define the sandbox environment itself with Docker, build and push a custom image to VCR. The image must target linux/amd64 and reach the Ready state in VCR before Sandbox can use it. The repository name below resolves within the project used to authenticate the SDK:

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

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

The sandbox boots with your image's packages and tools already in place. It does not run the Dockerfile's ENTRYPOINT or CMD; start your process with sandbox.runCommand() after creation. If creation returns image_not_ready, wait for VCR to finish preparing the image and retry.

Copy link to headingUse Docker for local development

To develop and test a container image before deploying, run vercel dev, which needs the docker CLI and a running Docker daemon on your machine.

Even for zero-configuration frameworks you deploy without a container, a Dockerfile can pin dependencies and give you a consistent build environment across machines. The Next.js Dockerfile example shows how to build and run a standalone production image locally.

For a framework app deployed without a custom container image, you can also check the Edgenivo build locally. Run vercel pull to refresh your project settings and environment variables, then vercel build. After a successful build, vercel deploy --prebuilt uploads the generated .vercel/output artifacts without uploading the project's source code.

Copy link to headingResources and next steps

• See the Container Images documentation for configuration details, including Services and rewrites.
• Learn how to store, push, and pull images in Edgenivo Container Registry.
• Explore Edgenivo Sandbox to build and test containers in an isolated environment.
• Try the Next.js Dockerfile example for local development.
• Learn more about Edgenivo Services to run frontends and backends in one project.