Custom images
This page covers the parts of building your own image that go beyond the Create an image walkthrough: how a custom image relates to a platform base image, what its build status actually means, and how a ready version ends up available in the create wizard. See Create an image for the step-by-step source, environment variable and lifecycle hook setup.
Building on a base image
Section titled “Building on a base image”A base image is required for every source kind - Dockerfile, container image and Git repository alike. Pick one in the Base image search picker - it shows the base’s operating system, architecture and description as you type - regardless of which source you chose.
The base doesn’t change what your source produces: your Dockerfile still builds however it builds, the container image reference is still pulled as-is, and the Git repository still builds the same way it always did. What the base controls is what that result is layered onto. The build starts from a copy of the base’s filesystem, overlays your build’s output on top of it (your files win wherever the two overlap), then restores the base’s own platform files - SSH configuration and, on bases that ship it, envd - so nothing in your build can remove or replace them. The kernel the built image boots is always the base’s kernel, never anything from your Dockerfile or container image.
Every custom image also gets the platform’s own guest agent (vcagent - lifecycle hooks, metrics, the exec API) freshly injected on every build, no matter which base you pick. Whether the image also gets envd, the agent behind the interactive web shell and the E2B SDK’s command/file operations, depends only on the base you chose - not on your source kind, and not on any FROM line inside your own Dockerfile: today that’s sandbox-base, debian-13, ubuntu-24.04 and ubuntu-26.04. Pick one of those for any source kind to get shell ingress; any other base leaves it unavailable on the resulting image. See Platform base images for what each base provides.
Version status lifecycle
Section titled “Version status lifecycle”Every build - the first one and every rebuild - produces a version that moves through:
| Status | Meaning |
|---|---|
| Pending | Queued, not yet picked up by a MicroVM node. |
| Building | A node is running the build now. |
| Ready | The build succeeded. This version can be used to create a MicroVM. |
| Error | The build failed. See its build log on the Versions tab for why. |
Only a ready version can be used to create a MicroVM or deploy a new run onto an existing one. Rebuilding never touches an existing ready version - it adds a new one, so MicroVMs already running the old version keep working undisturbed while the new one builds. The newest ready version becomes the image’s current version automatically.
Using it in the MicroVM create wizard
Section titled “Using it in the MicroVM create wizard”A custom image appears in the wizard’s image search badged Custom (a platform base shows Platform), searchable by name alongside every base image. Picking a version is optional - leave it empty to get the current (newest ready) version, or pick an older one explicitly to pin a MicroVM to it. An image with no ready version yet cannot be selected.