From 40df5b2cadb492403d0164892d3c112c3690c550 Mon Sep 17 00:00:00 2001
From: Mish Ushakov <10400064+mishushakov@users.noreply.github.com>
Date: Fri, 5 Jun 2026 15:26:04 +0200
Subject: [PATCH] Document customizing the sandbox template

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md          |  4 ++
 template/README.md | 94 ++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 95 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index fdffb05..23e6016 100644
--- a/README.md
+++ b/README.md
@@ -493,3 +493,7 @@ await desktop.wait(1000) // Wait for 1 second
 
 The desktop-like environment is based on Linux and [Xfce](https://www.xfce.org/) at the moment. We chose Xfce because it's a fast and lightweight environment that's also popular and actively supported. However, this Sandbox template is fully customizable and you can create your own desktop environment.
 Check out the sandbox template's code [here](./template/).
+
+## Customizing the sandbox template
+
+Need extra packages or a different desktop environment? You can build your own Desktop sandbox template. See the [template guide](./template/README.md) for a step-by-step walkthrough of creating, building, and using a custom template (as well as building the production `desktop` template).
diff --git a/template/README.md b/template/README.md
index d2db436..a71bbe3 100644
--- a/template/README.md
+++ b/template/README.md
@@ -2,14 +2,102 @@
 
 This is the template for the E2B Desktop Sandbox.
 
-## Building the template
+## Building the production template
+
+To build the official `desktop` template from this repo, use `build_prod.py`.
+This is the script CI and releases run.
+
+1. Install the build dependencies:
 
 ```bash
-poetry run python build_dev.py
+poetry install
+```
+
+2. Provide your credentials in `.env`:
+
+```
+E2B_API_KEY=e2b_***
 ```
 
-## Building the production image
+3. Build the template:
 
 ```bash
 poetry run python build_prod.py
 ```
+
+During development you can build the `desktop-dev` template instead:
+
+```bash
+poetry run python build_dev.py
+```
+
+If you want to customize the Desktop sandbox (e.g.: add a preinstalled package)
+you can do that by creating a [custom sandbox template](https://e2b.dev/docs/template/quickstart).
+
+## Creating a custom template
+
+1. Install E2B SDK
+
+```bash
+pip install e2b dotenv
+```
+
+2. Create a custom sandbox template:
+
+**template.py**
+
+```python
+from e2b import Template
+
+template = Template().from_template("desktop")
+```
+
+3. Create a build script:
+
+**build.py**
+
+```python
+from dotenv import load_dotenv
+from template import template
+from e2b import Template, default_build_logger
+
+load_dotenv()
+
+Template.build(
+    template,
+    alias="desktop-custom",
+    cpu_count=8,
+    memory_mb=8192,
+    on_build_logs=default_build_logger(),
+)
+```
+
+4. Set your environment variables in a `.env` file (loaded by `load_dotenv()`):
+
+```
+E2B_API_KEY=e2b_***
+```
+
+5. Build the template:
+
+```bash
+python build.py
+```
+
+6. Use the custom template:
+
+**Python**
+
+```python
+from e2b_desktop import Sandbox
+
+desktop = Sandbox.create(template="desktop-custom")
+```
+
+**JavaScript**
+
+```javascript
+import { Sandbox } from '@e2b/desktop'
+
+const desktop = await Sandbox.create('desktop-custom')
+```