Templates

Templates are pre-configured sandbox environments built from Dockerfiles. They let you define exactly what software, packages, and tools are available inside your Vibengine sandbox before it even starts.

Why Use Templates?

By default, every Vibengine sandbox starts from a minimal base image. This is fine for simple tasks, but in production you often need:

• Pre-installed packages — Skip waiting for pip install or npm install every time a sandbox boots.
• Custom system tools — Include CLI utilities, compilers, or databases that your workflows depend on.
• Faster startup times — Since everything is baked into the image, sandboxes launch in seconds instead of spending time on setup.
• Reproducible environments — Guarantee that every sandbox instance is identical, eliminating "works on my machine" issues.

How Templates Work

The template workflow follows three steps:

1. Define — Write a Dockerfile that describes your environment (base image, installed packages, configuration files, etc.).
2. Build — Use the ve CLI to build and push your template to the Vibengine infrastructure.
3. Use — Reference your template by name (and optionally a tag) when creating a sandbox in your code.

Dockerfile → ve template build → Sandbox("my-template")

Using a Template

Once a template is built, you reference it by its ID when creating a sandbox:

import { Sandbox } from "vibengine"

const sandbox = await Sandbox.create("my-template")

from vibengine import Sandbox

sandbox = Sandbox("my-template")

Template Lifecycle

Default vs Custom Templates

If you create a sandbox without specifying a template, Vibengine uses a built-in default environment with basic utilities pre-installed. Custom templates extend this — your Dockerfile starts FROM the Vibengine base image, so you inherit all the default tooling and add your own on top.

Prerequisites

Before working with templates, make sure you have:

1. The ve CLI installed and authenticated.
2. A valid VE_API_KEY configured in your environment.
3. Docker installed locally (used during the build process).

Ready to get started? Head to the Template Quickstart to build your first template.