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 projectmy-template:production // Within your projectacme/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
// These are equivalentconst sandbox1 = await Sandbox.create('my-template')const sandbox2 = await Sandbox.create('my-template:default')
# These are equivalentsandbox1 = Sandbox.create('my-template')sandbox2 = Sandbox.create('my-template:default')
Referencing a specific build
Instead of using a named tag, you can start a sandbox from a specific build by passing its build_id directly. This is useful when you need to pin a sandbox to an exact build artifact — for example, during debugging or when reproducing an issue from a known build.The format follows the same colon syntax as tags: <template>:<build_id> or <namespace>/<template>:<build_id>.You can find the build_id from the return value of Template.build() or by listing tags with Template.getTags() / Template.get_tags().
import { Sandbox } from 'e2b'// Start a sandbox from a specific build IDconst sandbox = await Sandbox.create('my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')// With namespaceconst sandbox2 = await Sandbox.create('acme/my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')
from e2b import Sandbox# Start a sandbox from a specific build IDsandbox = Sandbox.create('my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')# With namespacesandbox2 = Sandbox.create('acme/my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')
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 tagawait Template.build(template, 'my-template:v1.0.0')
from e2b import Template# Build with a specific version tagTemplate.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 artifactawait Template.build(template, 'my-template', { tags: ['v1.2.0', 'latest'] })
from e2b import Template# Build with multiple tags pointing to the same artifactTemplate.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.
import { Template } from 'e2b'// Assign a single tagawait Template.assignTags('my-template:v1.2.0', 'production')// Assign multiple tags at onceawait Template.assignTags('my-template:v1.2.0', ['production', 'stable'])
from e2b import Template# Assign a single tagTemplate.assign_tags('my-template:v1.2.0', 'production')# Assign multiple tags at onceTemplate.assign_tags('my-template:v1.2.0', tags=['production', 'stable'])
Remove tags
Remove a tag from a template. The underlying build artifact remains accessible via other tags.
import { Template } from 'e2b'// Remove a tagawait Template.removeTags('my-template', 'staging')
from e2b import Template# Remove a tagTemplate.remove_tags('my-template', 'staging')
Removing a tag does not delete the build artifact. Other tags pointing to the same build will continue to work.
List tags
Retrieve all tags for a template. Each tag includes the tag name, the associated build ID, and when the tag was assigned.
import { Template } from 'e2b'const tags = await Template.getTags('my-template')for (const tag of tags) { console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`)}
from e2b import Templatetags = Template.get_tags('my-template')for tag in tags: print(f"Tag: {tag.tag}, Build: {tag.build_id}, Created: {tag.created_at}")
Use cases
Semantic versioning
Use semantic version tags to track releases and enable rollbacks.
// Release versionsawait 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 versionconst sandbox = await Sandbox.create('api-server:v1.1.0')
# Release versionsTemplate.build(template, 'api-server:v1.0.0')Template.build(template, 'api-server:v1.1.0')Template.build(template, 'api-server:v2.0.0')# Create sandbox from specific versionsandbox = Sandbox.create('api-server:v1.1.0')
Environment tags
Use environment tags for deployment pipelines.
// Build new versionawait Template.build(template, 'my-app:v1.5.0')// Promote through environmentsawait Template.assignTags('my-app:v1.5.0', 'staging')// After testing, promote to productionawait Template.assignTags('my-app:v1.5.0', 'production')// Use in your applicationconst env = process.env.NODE_ENVconst sandbox = await Sandbox.create(`my-app:${env}`)
import os# Build new versionTemplate.build(template, 'my-app:v1.5.0')# Promote through environmentsTemplate.assign_tags('my-app:v1.5.0', 'staging')# After testing, promote to productionTemplate.assign_tags('my-app:v1.5.0', 'production')# Use in your applicationenv = os.environ.get('ENV', 'staging')sandbox = Sandbox.create(f'my-app:{env}')
Latest and stable tags
Maintain rolling tags that always point to specific versions.
// Build with version and latest tagawait Template.build(template, 'my-tool', { tags: ['v3.0.0', 'latest'] })// Mark a tested version as stableawait Template.assignTags('my-tool:v2.9.0', 'stable')// You can choose your risk toleranceconst latestSandbox = await Sandbox.create('my-tool:latest') // Newestconst stableSandbox = await Sandbox.create('my-tool:stable') // Tested
# Build with version and latest tagTemplate.build(template, 'my-tool', tags=['v3.0.0', 'latest'])# Mark a tested version as stableTemplate.assign_tags('my-tool:v2.9.0', 'stable')# You can choose your risk tolerancelatest_sandbox = Sandbox.create('my-tool:latest') # Neweststable_sandbox = Sandbox.create('my-tool:stable') # Tested