Skip to main content
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 alias:tag format, where alias is your template’s unique identifier and tag is the version label. 
my-template:v1.0.0
my-template:production
my-template:latest

​
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
// 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

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. 
import { Template } from 'e2b'

// Build with multiple tags pointing to the same artifact
await Template.build(template, ['my-template:v1.2.0', 'my-template:latest'])
When building with multiple tags, E2B creates a single build artifact that all tags reference. This saves build time and storage.

​
Managing Tags

You can manage tags on existing template builds without rebuilding.

​
Assign Tags

Use assignTag to add new tag(s) to an existing build. This is useful for promoting a tested version to production or marking a version as stable. 
import { Template } from 'e2b'

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

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

​
Delete Tags

Use deleteTag to remove a tag from a template. The underlying build artifact remains accessible via other tags. 
import { Template } from 'e2b'

// Remove a tag
await Template.deleteTag('my-template:staging')
Deleting 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. 
// 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. 
// Build new version
await Template.build(template, 'my-app:v1.5.0')

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

// After testing, promote to production
await Template.assignTag('my-app:v1.5.0', 'my-app: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. 
// Build with version and latest tag
await Template.build(template, ['my-tool:v3.0.0', 'my-tool:latest'])

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

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