Skip to main content
Template aliases are unique identifiers used to reference and create sandboxes from your templates. They serve as human-readable names that make it easy to identify and use your templates across your applications.

​
What is a Template Alias?

An alias is a string identifier that you assign to a template when building it. Once a template is built with an alias, you can use that alias to create sandboxes from the template. 
// Build a template with an alias
await Template.build(template, {
  alias: 'my-python-env',
  cpuCount: 2,
  memoryMB: 2048,
})

// Create a sandbox using the alias
const sandbox = await Sandbox.create('my-python-env')

​
Uniqueness Requirement

Template aliases must be globally unique across the entire E2B platform, not just within your team or account. This means if another user has already claimed an alias, you cannot use it for your template.
When choosing an alias, consider using:
  • Your company or project name as a prefix (e.g., acme-api-server)
  • Version numbers or environment indicators (e.g., myapp-v2, myapp-staging)
  • Descriptive names that indicate the template’s purpose (e.g., data-analysis-python)

​
Common Use Cases

​
Development and Production Environments

Use different aliases for different environments: 
// Development template
await Template.build(template, {
  alias: 'myapp-dev',
  cpuCount: 1,
  memoryMB: 1024,
})

// Production template
await Template.build(template, {
  alias: 'myapp-prod',
  cpuCount: 4,
  memoryMB: 4096,
})

​
Multiple Template Variants

Create different variants of the same template with different configurations: 
// Small instance
await Template.build(template, {
  alias: 'myapp-small',
  cpuCount: 1,
  memoryMB: 512,
})

// Large instance
await Template.build(template, {
  alias: 'myapp-large',
  cpuCount: 8,
  memoryMB: 16384,
})
When building variants with the same template definition but different CPU/RAM configurations, E2B’s caching system will reuse common layers, making subsequent builds much faster.

​
Checking Alias Availability

Before building a new template, you can check if an alias is already in use with the aliasExists method: 
import { Template } from 'e2b'

const desiredAlias = 'my-new-template'

const exists = await Template.aliasExists(desiredAlias)

if (!exists) {
  // Alias is available, proceed with build
  await Template.build(template, {
    alias: desiredAlias,
    cpuCount: 2,
    memoryMB: 2048,
  })
  console.log('Template built successfully')
} else {
  console.log('Alias already taken, please choose a different name')
}

​
Return Value

The aliasExists method returns:
  • true / True if the alias is already in use (either by you or another user)
  • false / False if the alias is available
The method will return true for both public templates and your own private templates, but false if the alias doesn’t exist or if you don’t have access to it.

​
Verifying Template Availability

You can also use aliasExists to verify that a template is available before attempting to create a sandbox: 
import { Sandbox, Template } from 'e2b'

const templateAlias = 'my-python-env'

const exists = await Template.aliasExists(templateAlias)

if (!exists) {
  console.log('Template not found, building it first...')
  await Template.build(template, {
    alias: templateAlias,
    cpuCount: 2,
    memoryMB: 2048,
  })
}

const sandbox = await Sandbox.create(templateAlias)
console.log('Sandbox created successfully')

​
Best Practices

  1. Use descriptive names: Choose aliases that clearly indicate the template’s purpose or configuration
  2. Include versioning: Consider adding version numbers to your aliases for better version management (e.g., myapp-v1, myapp-v2)
  3. Check availability first: Always check if an alias is available before attempting to build with it
  4. Use consistent naming: Establish a naming convention for your team and stick to it
  5. Document your aliases: Keep a record of which aliases are used for which purposes in your team