# Template Quick Start
<subtitle>Learn how to define, build, and deploy custom sandbox templates to quickly customize Agent runtime environments.</subtitle>

>
> **Prerequisites**: Please complete [API Key Configuration](/docs/agent-sandbox/product/01-prerequisites) first

Templates are blueprints for sandboxes. They allow you to pre-install software, configure environment variables, pre-configure files, and set start commands and readiness checks. Through templates, you can ensure that Agents start in a fully ready environment each time without additional waiting for installation processes.

---

## Method 1: Using CLI (Recommended)

CLI is the most convenient way to manage templates.

1.  **Install CLI**
    ```bash
    npm i -g @ucloud-sdks/ucloud-sandbox-cli
    ```

2.  **Initialize Project**
    Execute the following command and configure your new template according to interactive prompts.
    ```bash
    ucloud-sandbox-cli template init
    ```

3.  **Build and Use**
    After initialization, CLI will generate a project structure including `README.md`. You can build and deploy according to the instructions.

---

## Method 2: Using Python SDK

If you want to integrate the template build process into your existing Python workflow, you can use SDK mode.

### 1. Write Template Definition (`template.py`)

```python
from ucloud_sandbox import Template, wait_for_timeout

template = (
    Template()
    .from_base_image()  # Use official pre-configured base image
    .set_envs({
        "APP_VERSION": "1.0.0",
        "DEBUG": "true"
    })
    .set_start_cmd("echo 'Environment is ready'", wait_for_timeout(5_000))
)
```

### 2. Build Template (`build.py`)

```python
from ucloud_sandbox import Template, default_build_logger

if __name__ == '__main__':
    # Call build interface and specify alias
    Template.build(
        template,
        alias="my-agent-env",
        cpu_count=2,
        memory_mb=2048,
        on_build_logs=default_build_logger(),
    )
```

### 3. Execute Build

```bash
python build.py
```

---

## Using Custom Templates

Once the template is successfully built, you can start sandboxes through its **Alias**.

```python
from ucloud_sandbox import Sandbox

# Create sandbox using the template alias just built
sbx = Sandbox.create(template="my-agent-env")

# Check environment variables
result = sbx.commands.run("echo $APP_VERSION")
print(f"Version: {result.stdout}")  # Output: Version: 1.0.0
```

>
> **Tip**: Template aliases are your globally unique identifiers. In production environments, it is recommended to manage version iterations through aliases.