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}")
getTags() / get_tags() reports each tag’s latest assignment, even while the assigned build is still building or has failed. To see which ready build each tag points at, list the template’s builds and filter by tag. To read the build a sandbox starts from without a tag, get the template’s default build.
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
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.