feat: add documentation for template versioning with tags

docs.json

@@ -104,7 +104,8 @@
               "docs/template/defining-template",
               "docs/template/start-ready-command",
               "docs/template/build",
-              "docs/template/aliases",
+              "docs/template/names",
+              "docs/template/versioning",
               "docs/template/logging",
               "docs/template/error-handling",
               {
@@ -270,6 +271,11 @@
     }
   },
   "redirects": [
+    {
+      "source": "/docs/template/aliases",
+      "destination": "/docs/template/names",
+      "permanent": true
+    },
     {
       "source": "/docs/sandbox-templates/overview",
       "destination": "/docs/sandbox-template",

docs/mcp/custom-templates.mdx

@@ -3,10 +3,10 @@
 description: Use MCP servers with custom sandbox templates
 ---
 
 You can prepull MCP server Docker images during template build time to significantly improve runtime performance.
 ## How it works
 
 When you build a template with prepulled MCP servers, the Docker images for those servers are downloaded and cached during the build process. This means when you create a sandbox from that template, the MCP servers are ready to use immediately without waiting for image downloads.
 
 <Info>
 You must use the MCP gateway enabled template (`mcp-gateway`) as your base template to use this feature.
@@ -14,7 +14,7 @@
 
 ## Building a template with MCP servers
 
 Use the `addMcpServer()` method (TypeScript) or `add_mcp_server()` method (Python) to prepull MCP server images during template build. You can pass a single server or an array of servers.
 
 The server names (like `"browserbase"` and `"exa"`) correspond to the keys defined in the [Available Servers](/docs/mcp/available-servers) documentation.
 
@@ -28,8 +28,7 @@
   .fromTemplate("mcp-gateway")
   .addMcpServer(["browserbase", "exa"]);
 
-await Template.build(template, {
-  alias: "my-mcp-gateway",
+await Template.build(template, 'my-mcp-gateway', {
   cpuCount: 8,
   memoryMB: 8192,
   onBuildLogs: defaultBuildLogger(),
@@ -50,7 +49,7 @@
 
 Template.build(
     template,
-    alias="my-mcp-gateway",
+    'my-mcp-gateway',
     cpu_count=8,
     memory_mb=8192,
     on_build_logs=default_build_logger(),
@@ -61,7 +60,7 @@
 
 ## Using the template
 
-Once built, create sandboxes from your template alias. You still need to provide the configuration for each MCP server.
+Once built, create sandboxes from your template. You still need to provide the configuration for each MCP server.
 
 <CodeGroup>
 

docs/quickstart/install-custom-packages.mdx

@@ -71,8 +71,7 @@ import { Template, defaultBuildLogger } from 'e2b';
 import { template } from './template';
 
 async function main() {
-  await Template.build(template, {
-    alias: "custom-packages",
+  await Template.build(template, 'custom-packages', {
     cpuCount: 2,
     memoryMB: 2048,
     onBuildLogs: defaultBuildLogger(),
@@ -93,7 +92,7 @@ load_dotenv()
 if __name__ == '__main__':
     Template.build(
         template,
-        alias="custom-packages",
+        'custom-packages',
         cpu_count=2,
         memory_mb=2048,
         on_build_logs=default_build_logger(),

docs/template/build.mdx

@@ -10,8 +10,7 @@ The `build` method builds the template and waits for the build to complete. It r
 <CodeGroup>
 
 ```typescript JavaScript & TypeScript wrap
-const buildInfo = await Template.build(template, {
-  alias: 'my-template', // Template alias (required)
+const buildInfo = await Template.build(template, 'my-template', {
   cpuCount: 2, // CPU cores
   memoryMB: 2048, // Memory in MB
   skipCache: false, // Configure cache skip (except for files)
@@ -20,13 +19,13 @@ const buildInfo = await Template.build(template, {
   domain: 'your-domain', // Override domain
 })
 
-// buildInfo contains: { alias, templateId, buildId }
+// buildInfo contains: { name, templateId, buildId }
 ```
 
 ```python Python wrap
 build_info = Template.build(
     template,
-    alias="my-template",  # Template alias (required)
+    'my-template',
     cpu_count=2,  # CPU cores
     memory_mb=2048,  # Memory in MB
     skip_cache=False,  # Configure cache skip (except for files)
@@ -35,7 +34,7 @@ build_info = Template.build(
     domain="your-domain",  # Override domain
 )
 
-# build_info contains: BuildInfo(alias, template_id, build_id)
+# build_info contains: BuildInfo(name, template_id, build_id)
 ```
 
 </CodeGroup>
@@ -47,24 +46,23 @@ The `buildInBackground` method starts the build process and returns immediately
 <CodeGroup>
 
 ```typescript JavaScript & TypeScript wrap
-const buildInfo = await Template.buildInBackground(template, {
-  alias: 'my-template',
+const buildInfo = await Template.buildInBackground(template, 'my-template', {
   cpuCount: 2,
   memoryMB: 2048,
 })
 
-// Returns immediately with: { alias, templateId, buildId }
+// Returns immediately with: { name, templateId, buildId }
 ```
 
 ```python Python wrap
 build_info = Template.build_in_background(
     template,
-    alias="my-template",
+    'my-template',
     cpu_count=2,
     memory_mb=2048,
 )
 
-# Returns immediately with: BuildInfo(alias, template_id, build_id)
+# Returns immediately with: BuildInfo(name, template_id, build_id)
 ```
 
 </CodeGroup>
@@ -100,8 +98,7 @@ status = Template.get_build_status(
 
 ```typescript JavaScript & TypeScript wrap
 // Start build in background
-const buildInfo = await Template.buildInBackground(template, {
-  alias: 'my-template',
+const buildInfo = await Template.buildInBackground(template, 'my-template', {
   cpuCount: 2,
   memoryMB: 2048,
 })
@@ -137,7 +134,7 @@ if (status === 'ready') {
 # Start build in background
 build_info = Template.build_in_background(
     template,
-    alias="my-template",
+    'my-template',
     cpu_count=2,
     memory_mb=2048,
 )

docs/template/caching.mdx

@@ -43,17 +43,16 @@ To force rebuild the whole template, you can use also `skipCache`/`skip_cache` p
 
 <CodeGroup>
 
-```typescript JavaScript & TypeScript wrap highlight={3}
-Template.build(template, {
-  alias: 'my-template',
+```typescript JavaScript & TypeScript wrap highlight={2}
+Template.build(template, 'my-template', {
   skipCache: true, // Configure cache skip (except for files)
 })
 ```
 
 ```python Python wrap highlight={4}
 Template.build(
     template,
-    alias="my-template",
+    'my-template',
     skip_cache=True,  # Configure cache skip (except for files)
 )
 ```
@@ -91,7 +90,7 @@ template = (
 
 ## Use Case for Caching
 You can leverage caching to create templates with multiple variants (e.g., different RAM or CPU) while reusing the common layers.
-When building the template, just change the template alias to a specific RAM/CPU configuration (e.g., `my-template-2cpu-2gb`, `my-template-1cpu-4gb`), keep the rest of the template definition the same, and the build process will reuse the cached layers.
+When building the template, just change the template name to a specific RAM/CPU configuration (e.g., `my-template-2cpu-2gb`, `my-template-1cpu-4gb`), keep the rest of the template definition the same, and the build process will reuse the cached layers.
 
 ## Optimize Build Times
 To optimize build times, place frequently changing commands (e.g., copying source code) towards the end of your template definition. This way, earlier layers can be cached and reused more often.

docs/template/error-handling.mdx

@@ -11,9 +11,7 @@ The SDK provides specific error types:
 import { AuthError, BuildError, FileUploadError } from 'e2b';
 
 try {
-  await Template.build(template, {
-    alias: "my-template",
-  });
+  await Template.build(template, 'my-template');
 } catch (error) {
   if (error instanceof AuthError) {
     console.error("Authentication failed:", error.message);
@@ -29,7 +27,7 @@ try {
 from e2b import AuthError, BuildError, FileUploadError
 
 try:
-    Template.build(template, alias="my-template")
+    Template.build(template, 'my-template')
 except AuthError as error:
     print(f"Authentication failed: {error}")
 except FileUploadError as error:

docs/template/examples/claude-code.mdx

@@ -41,8 +41,7 @@ template = (
 import { Template, defaultBuildLogger } from 'e2b'
 import { template as claudeCodeTemplate } from './template'
 
-Template.build(claudeCodeTemplate, {
-  alias: 'claude-code',
+Template.build(claudeCodeTemplate, 'claude-code', {
   cpuCount: 1,
   memoryMB: 1024,
   onBuildLogs: defaultBuildLogger(),
@@ -54,8 +53,7 @@ Template.build(claudeCodeTemplate, {
 from e2b import Template, default_build_logger
 from .template import template as claudeCodeTemplate
 
-Template.build(claudeCodeTemplate,
-    alias="claude-code",
+Template.build(claudeCodeTemplate, 'claude-code',
     cpu_count=1,
     memory_mb=1024,
     on_build_logs=default_build_logger(),

docs/template/examples/desktop.mdx

@@ -164,8 +164,7 @@ sleep 2
 import { Template, defaultBuildLogger } from 'e2b'
 import { template as desktopTemplate } from './template'
 
-await Template.build(desktopTemplate, {
-  alias: 'desktop',
+await Template.build(desktopTemplate, 'desktop', {
   cpuCount: 8,
   memoryMB: 8192,
   onBuildLogs: defaultBuildLogger(),
@@ -177,8 +176,7 @@ await Template.build(desktopTemplate, {
 from e2b import Template, default_build_logger
 from .template import template as desktopTemplate
 
-Template.build(desktopTemplate,
-    alias="desktop",
+Template.build(desktopTemplate, 'desktop',
     cpu_count=8,
     memory_mb=8192,
     on_build_logs=default_build_logger(),

docs/template/examples/expo.mdx

@@ -45,8 +45,7 @@ template = (
 import { Template, defaultBuildLogger } from 'e2b'
 import { template as expoTemplate } from './template'
 
-Template.build(expoTemplate, {
-  alias: 'expo-app',
+Template.build(expoTemplate, 'expo-app', {
   cpuCount: 4,
   memoryMB: 8192,
   onBuildLogs: defaultBuildLogger(),
@@ -58,8 +57,7 @@ Template.build(expoTemplate, {
 from e2b import Template, default_build_logger
 from .template import template as expoTemplate
 
-Template.build(expoTemplate,
-    alias="expo-app",
+Template.build(expoTemplate, 'expo-app',
     cpu_count=4,
     memory_mb=8192,
     on_build_logs=default_build_logger(),

docs/template/examples/nextjs-bun.mdx

@@ -3,7 +3,7 @@
 description: "Next.js web app running in the sandbox using Bun"
 ---
 
 Basic Next.js app with Tailwind and shadcn UI using Bun.
 
 <Note>
     The development server runs on port 3000 as soon as the sandbox is ready.
@@ -53,8 +53,7 @@
 import { Template, defaultBuildLogger } from 'e2b'
 import { template as nextJSTemplate } from './template'
 
-Template.build(nextJSTemplate, {
-  alias: 'nextjs-app-bun',
+Template.build(nextJSTemplate, 'nextjs-app-bun', {
   cpuCount: 4,
   memoryMB: 4096,
   onBuildLogs: defaultBuildLogger(),
@@ -66,8 +65,7 @@
 from e2b import Template, default_build_logger
 from .template import template as nextjsTemplate
 
-Template.build(nextjsTemplate,
-    alias="nextjs-app-bun",
+Template.build(nextjsTemplate, 'nextjs-app-bun',
     cpu_count=4,
     memory_mb=4096,
     on_build_logs=default_build_logger(),

docs/template/examples/nextjs.mdx

@@ -3,7 +3,7 @@
 description: "Next.js web app running in the sandbox using Node.js"
 ---
 
 Basic Next.js app with Tailwind and shadcn UI
 
 <Note>
     The development server runs on port 3000 as soon as the sandbox is ready.
@@ -55,8 +55,7 @@
 import { Template, defaultBuildLogger } from 'e2b'
 import { template as nextJSTemplate } from './template'
 
-Template.build(nextJSTemplate, {
-  alias: 'nextjs-app',
+Template.build(nextJSTemplate, 'nextjs-app', {
   cpuCount: 4,
   memoryMB: 4096,
   onBuildLogs: defaultBuildLogger(),
@@ -68,8 +67,7 @@
 from e2b import Template, default_build_logger
 from .template import template as nextjsTemplate
 
-Template.build(nextjsTemplate,
-    alias="nextjs-app",
+Template.build(nextjsTemplate, 'nextjs-app',
     cpu_count=4,
     memory_mb=4096,
     on_build_logs=default_build_logger(),

docs/template/logging.mdx

@@ -12,8 +12,7 @@ We provide a default logger that you can use to filter logs by level:
 ```typescript JavaScript & TypeScript
 import { Template, defaultBuildLogger } from 'e2b';
 
-await Template.build(template, {
-  alias: "my-template",
+await Template.build(template, 'my-template', {
   onBuildLogs: defaultBuildLogger({
     minLevel: "info", // Minimum log level to show
   }),
@@ -25,7 +24,7 @@ from e2b import Template, default_build_logger
 
 Template.build(
     template,
-    alias="my-template",
+    'my-template',
     on_build_logs=default_build_logger(
         min_level="info",  # Minimum log level to show
     )
@@ -68,14 +67,14 @@ def custom_logger(log_entry):
     time = log_entry.timestamp.isoformat()
     print(f"[{time}] {log_entry.level.upper()}: {log_entry.message}")
 
-Template.build(template, alias="my-template", on_build_logs=custom_logger)
+Template.build(template, 'my-template', on_build_logs=custom_logger)
 
 # Filter by log level
 def error_logger(log_entry):
     if log_entry.level in ["error", "warn"]:
         print(f"ERROR/WARNING: {log_entry}", file=sys.stderr)
 
-Template.build(template, alias="my-template", on_build_logs=error_logger)
+Template.build(template, 'my-template', on_build_logs=error_logger)
 ```
 
 </CodeGroup>