feat: add documentation for template versioning with tags (#83)

Author: dobrac

docs.json

@@ -107,7 +107,8 @@
               "docs/template/defining-template",
               "docs/template/start-ready-command",
               "docs/template/build",
-              "docs/template/aliases",
+              "docs/template/names",
+              "docs/template/tags",
               "docs/template/logging",
               "docs/template/error-handling",
               {
@@ -282,6 +283,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

@@ -28,8 +28,7 @@ export const template = Template()
   .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 = (
 
 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 @@ Template.build(
 
 ## 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/aliases.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/build.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/caching.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/error-handling.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(),