Images

An image is the file system a microVM starts from: the operating system, the language runtime and any tools you preinstall. Start from a built-in image for a standard runtime, and build a custom image when every microVM needs the same extra packages, so you install them once instead of on every create.

Built-in images

Pass the name as image when you create a microVM. Without image, a microVM starts from node22.

Each one is built from the official image in the Based on column, so apt-get and the usual Debian or Ubuntu tools are available. List the images available to an application, built-in and custom, with client.microvms.images.list(), gigadrive microvms images ls or GET /microvm-images?applicationId=....

How an image runs

A microVM starts the image's file system but not its program: the image's entrypoint and default command are ignored, and nothing runs until you start a command. The image's user, working directory and environment variables still apply, as the defaults for every command. Start a server as a detached command.

Writes go to the microVM's own disk on top of the image, so installing packages or changing files never alters the image or any other microVM.

Build a custom image

Create an image from a public registry reference or from a Dockerfile. The build runs in the background, and the image is ready to use when its status is ready. This example builds an image with pandas and numpy preinstalled and starts a microVM from it.

import { GigadriveClient, MicroVM } from '@gigadrive/sdk';

const client = new GigadriveClient();

const image = await client.microvms.images.create({
  name: 'python-data',
  from: { dockerfile: 'FROM python:3.13-bookworm\nRUN pip install pandas numpy\n' },
});
await client.microvms.images.waitUntilReady(image.id);

await using vm = await MicroVM.create({ image: 'python-data' });

A registry reference must point to a public linux/amd64 image. A Dockerfile is built without a build context: it sees only its own text, so COPY and ADD of local files fail. Fetch what you need in a RUN step instead, or copy it from another image with COPY --from. Creating a microVM from an image that is not ready yet answers 409 with image_not_ready.

Build states

Names and limits

• A name is 1 to 63 characters of lowercase letters, digits, ., _ and -, and starts with a letter or a digit.
• A name is unique within its application. Two applications can each have an image called python-data.
• A Dockerfile is at most 256 KiB.
• Your plan sets how many custom images your organization can keep across all its applications: 3 on Starter, 50 on Pro and 500 on Enterprise. A build past that answers 429 with quota_exceeded. See Limits and pricing.

Delete an image you no longer need with gigadrive microvms images rm or DELETE /microvm-images/{id}. Deleting is refused with 409 and image_in_use while a running microVM uses the image, so stop those first. Built-in images cannot be deleted.

Listing and reading images needs the network:microvm_images:read scope, building one needs network:microvm_images:write, and deleting one needs network:microvm_images:delete.