Template Tags

Tags let you version your templates so you can maintain multiple configurations of the same environment, roll back to previous versions, and promote builds through development stages.

How Tags Work

Every template build is associated with a tag — a string label that identifies a specific version of the template. When you create a sandbox, you can specify which tag to use.

• If you build without specifying a tag, the build is tagged as latest.
• If you specify a tag, the build is associated with that tag name.
• Multiple tags can exist for the same template simultaneously.

my-template:latest    → most recent build
my-template:v1.0.0    → pinned production version
my-template:staging   → current staging version

Building with a Tag

Use the --tag flag when building:

# Build with default "latest" tag
ve template build

# Build with a custom tag
ve template build --tag v1.0.0

# Build with a stage-based tag
ve template build --tag staging

Using Tags in Code

When creating a sandbox, append the tag to the template ID with a colon separator:

import { Sandbox } from "vibengine"

// Uses the "latest" tag (default)
const sandbox1 = await Sandbox.create("my-template")

// Uses a specific version tag
const sandbox2 = await Sandbox.create("my-template:v1.0.0")

// Uses the staging tag
const sandbox3 = await Sandbox.create("my-template:staging")

from vibengine import Sandbox

# Uses the "latest" tag (default)
sandbox1 = Sandbox("my-template")

# Uses a specific version tag
sandbox2 = Sandbox("my-template:v1.0.0")

# Uses the staging tag
sandbox3 = Sandbox("my-template:staging")

The latest Tag

The latest tag has special behavior:

• It is assigned automatically when you run ve template build without a --tag flag.
• When you create a sandbox with just the template ID (no colon), Vibengine uses latest.
• Every untagged build overwrites the previous latest.

Tagging Strategy

Here are recommended approaches for managing template tags:

Semantic Versioning

Use version numbers to track breaking and non-breaking changes:

ve template build --tag v1.0.0   # Initial release
ve template build --tag v1.1.0   # Added new packages
ve template build --tag v2.0.0   # Changed base image (breaking)

Environment-Based Tags

Use tags that correspond to deployment stages:

ve template build --tag dev       # Development — latest experiments
ve template build --tag staging   # Staging — pre-production testing
ve template build --tag prod      # Production — stable, verified

Date-Based Tags

Use dates for audit trails and easy identification:

ve template build --tag 2026-02-21
ve template build --tag 2026-03-15

Listing Tags

View all tags for your templates:

ve template list

┌──────────────────┬────────────┬─────────────────────┐
│ ID               │ Tag        │ Last Built          │
├──────────────────┼────────────┼─────────────────────┤
│ my-template      │ latest     │ 2026-02-21 14:00:00 │
│ my-template      │ v1.0.0     │ 2026-02-15 09:30:00 │
│ my-template      │ staging    │ 2026-02-20 11:45:00 │
│ data-science     │ latest     │ 2026-02-19 16:20:00 │
└──────────────────┴────────────┴─────────────────────┘

Promoting Between Stages

A common workflow is to build with staging, test, then rebuild with prod:

# Build and test with staging tag
ve template build --tag staging
# ... run tests against "my-template:staging" ...

# Once verified, build the same Dockerfile with the prod tag
ve template build --tag prod

Deleting a Tagged Version

Currently, deleting individual tags is not supported. You can delete the entire template with ve template delete <id>, which removes all tags.

Best Practices

• Pin versions in production — Always use explicit tags like v1.0.0 rather than latest in production code.
• Document tag meanings — Keep a changelog or README in your template directory noting what each version includes.
• Test before promoting — Use staging tags to verify templates before pointing production code at them.
• Avoid overwriting production tags — Treat production tags as immutable. Create new version numbers instead of overwriting existing ones.

Next Steps

• Build templates — Learn how the build process works
• Template examples — Browse complete working templates