Custom kits
This page covers the parts of building your own kit that go beyond the Create a kit walkthrough: how a custom kit relates to a platform base kit, what its build status actually means, and how a ready version ends up available in the launcher. See Create a kit for the step-by-step source, environment variable and lifecycle hook setup.
Building on a base kit
Section titled “Building on a base kit”A base kit is required for every source type - Dockerfile, container image and Git repository alike. Pick one in the Base kit 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 kit boots is always the base’s kernel, never anything from your Dockerfile or container image.
Every custom kit 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 kit also gets envd, the agent behind the interactive web shell and the E2B SDK’s command/file operations, depends on the base you chose - not on your source type, 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 type to get shell ingress; any other base leaves it unavailable on the resulting kit. See Platform base kits for what each base provides.
Version status lifecycle
Section titled “Version status lifecycle”Every build - the initial one and every rebuild - produces a version that moves through:
| Status | Meaning |
|---|---|
| Pending | Queued, not yet picked up by a sandbox node. |
| Building | A node is running the build now. |
| Ready | The build succeeded. This version can be used to create a sandbox. |
| Error | The build failed. See its build log on the Versions tab for why. |
A ready version is required to create a sandbox or deploy a new run onto an existing one. Rebuilding never touches an existing ready version - it adds a new one, so sandboxes already running the old version keep working undisturbed while the new one builds. The newest ready version becomes the kit’s current version automatically.
Using it in the sandbox launcher
Section titled “Using it in the sandbox launcher”A custom kit appears in the launcher kit picker badged Custom (a platform base shows Platform), searchable by name alongside every base kit. Picking a version is optional - leave it empty to get the current (newest ready) version, or pick an older one explicitly to pin a sandbox to it. An kit with no ready version yet cannot be selected.