Template Tags & Versioning

Use tags to version your templates and manage environment-based deployments

Template versioning allows you to maintain multiple versions of the same template using tags. This enables workflows like semantic versioning, environment-based deployments, and gradual rollouts.

Tag Format

Tags follow the name:tag format, where name is your template’s identifier and tag is the version label.

my-template:v1.0.0              // Within your team
my-template:production          // Within your team
acme/my-template:v1.0.0         // Full namespaced reference

The Default Tag

When you build or reference a template without specifying a tag, E2B uses the default tag automatically. This means:

• my-template is equivalent to my-template:default
• Existing templates without tags continue to work seamlessly

JavaScript & TypeScript

// These are equivalent
const sandbox1 = await Sandbox.create('my-template')
const sandbox2 = await Sandbox.create('my-template:default')

Building with Tags

You can build templates with one or more tags to create versioned builds.

Single Tag

JavaScript & TypeScript

import { Template } from 'e2b'

// Build with a specific version tag
await Template.build(template, 'my-template:v1.0.0')

Multiple Tags

Build with multiple tags to assign several version labels to the same build artifact.

JavaScript & TypeScript

import { Template } from 'e2b'

// Build with multiple tags pointing to the same artifact
await Template.build(template, 'my-template', { tags: ['v1.2.0', 'latest'] })

Managing Tags

You can manage tags on existing template builds without rebuilding.

Assign Tags

Assign new tag(s) to an existing build. This is useful for promoting a tested version to production or marking a version as stable.

JavaScript & TypeScript

import { Template } from 'e2b'

// Assign a single tag
await Template.assignTags('my-template:v1.2.0', 'production')

// Assign multiple tags at once
await Template.assignTags('my-template:v1.2.0', ['production', 'stable'])

Remove Tags

Remove a tag from a template. The underlying build artifact remains accessible via other tags.

JavaScript & TypeScript

import { Template } from 'e2b'

// Remove a tag
await Template.removeTags('my-template', 'staging')

Removing a tag does not delete the build artifact. Other tags pointing to the same build will continue to work.

Use Cases

Semantic Versioning

Use semantic version tags to track releases and enable rollbacks.

JavaScript & TypeScript

// Release versions
await Template.build(template, 'api-server:v1.0.0')
await Template.build(template, 'api-server:v1.1.0')
await Template.build(template, 'api-server:v2.0.0')

// Create sandbox from specific version
const sandbox = await Sandbox.create('api-server:v1.1.0')

Environment Tags

Use environment tags for deployment pipelines.

JavaScript & TypeScript

// Build new version
await Template.build(template, 'my-app:v1.5.0')

// Promote through environments
await Template.assignTags('my-app:v1.5.0', 'staging')

// After testing, promote to production
await Template.assignTags('my-app:v1.5.0', 'production')

// Use in your application
const env = process.env.NODE_ENV
const sandbox = await Sandbox.create(`my-app:${env}`)

Latest and Stable Tags

Maintain rolling tags that always point to specific versions.

JavaScript & TypeScript

// Build with version and latest tag
await Template.build(template, 'my-tool', { tags: ['v3.0.0', 'latest'] })

// Mark a tested version as stable
await Template.assignTags('my-tool:v2.9.0', 'stable')

// You can choose your risk tolerance
const latestSandbox = await Sandbox.create('my-tool:latest')  // Newest
const stableSandbox = await Sandbox.create('my-tool:stable')  // Tested