Template Quickstart

This guide walks you through creating, building, and using your first custom Vibengine template. By the end, you will have a sandbox environment with your own pre-installed packages.

Prerequisites

Make sure you have the following ready:

• The ve CLI installed (ve --version to verify)
• A valid VE_API_KEY set in your environment
• Docker running on your local machine

Step 1: Initialize a Template

Create a new directory for your template and run the init command:

mkdir my-template && cd my-template
ve template init

This generates two files:

my-template/
├── ve.toml          # Template configuration (name, ID)
└── Dockerfile       # Your environment definition

The ve.toml file contains metadata about your template:

# This is a Vibengine template config
id = "my-template"
dockerfile = "Dockerfile"

Step 2: Edit the Dockerfile

Open the generated Dockerfile. By default it looks like this:

FROM vibengine/base:latest

Let us customize it to include Python with some common packages:

FROM vibengine/base:latest

RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install requests numpy pandas

# Set the working directory for sandboxes
WORKDIR /home/user

Step 3: Build the Template

Build and push your template to Vibengine with a single command:

ve template build

You will see output similar to:

Building template my-template...
Step 1/4 : FROM vibengine/base:latest
 ---> a1b2c3d4e5f6
Step 2/4 : RUN apt-get update && apt-get install -y ...
 ---> Running in f6e5d4c3b2a1
Step 3/4 : RUN pip3 install requests numpy pandas
 ---> Running in 1a2b3c4d5e6f
Step 4/4 : WORKDIR /home/user
 ---> Running in 6f5e4d3c2b1a

Template my-template built successfully!
Template ID: my-template

The build process runs on Vibengine infrastructure and typically takes 1-3 minutes depending on the packages you install.

Step 4: Use Your Template

Now use your custom template when creating a sandbox:

import { Sandbox } from "vibengine"

async function main() {
  // Create a sandbox from your custom template
  const sandbox = await Sandbox.create("my-template")

  // Python and packages are already available
  const result = await sandbox.commands.run(
    "python3 -c \"import numpy; print(numpy.__version__)\""
  )
  console.log(result.stdout) // e.g., "1.26.4"

  await sandbox.close()
}

main()

from vibengine import Sandbox

# Create a sandbox from your custom template
sandbox = Sandbox("my-template")

# Python and packages are already available
result = sandbox.commands.run(
    "python3 -c \"import numpy; print(numpy.__version__)\""
)
print(result.stdout)  # e.g., "1.26.4"

sandbox.close()

Step 5: Iterate

When you need to update your template, simply edit the Dockerfile and rebuild:

# Edit Dockerfile with your changes
ve template build

Each build creates a new version. You can also tag builds for version control — see Template Tags for details.

Verify Your Templates

List all your published templates at any time:

ve template list

┌──────────────┬────────────┬─────────────────────┐
│ ID           │ Tag        │ Last Built          │
├──────────────┼────────────┼─────────────────────┤
│ my-template  │ latest     │ 2026-02-21 10:30:00 │
└──────────────┴────────────┴─────────────────────┘

Next Steps

• Dockerfile guide — Learn best practices for writing template Dockerfiles
• Build process — Understand the build pipeline and troubleshoot failures
• Template examples — Browse ready-to-use templates for common setups