# Quick start
<subtitle>Start using custom sandbox templates</subtitle>

UCloud Sandbox templates allow you to define custom sandbox environments. You can define a base image, environment variables, copy files, run commands, and set up a [start command](/docs/agent-sandbox/template/start-ready-command.md#start command) that runs during the template build and is captured in a snapshot - so that when you create a sandbox from the template, the process is already running. This provides your users with a fully configured sandbox, with running processes readily available and zero startup time.

There are two ways to create a new template:
- Using CLI
- Define manually using SDK

## Using CLI

You can create new templates using the UCloud Sandbox CLI.

### Install UCloud Sandbox CLI

```bash
curl -sS https://raw.githubusercontent.com/ucloud/ucloud-sandbox-cli/main/install.sh | sh
```

### Initialize new template

```bash
ucloud-sandbox-cli template init
```

### Follow the prompts

Follow the prompts to create a new template.

### Finish

Examine the generated `template.dockerfile` and `ucloud-template.json` files, edit the Dockerfile to define your environment, and build using the following command:

```bash
ucloud-sandbox-cli template build <template name>
```

## Manually define using SDK

### Install Python SDK

```bash
pip install ucloud-sandbox
```

Create `.env` file

```bash
UCLOUD_SANDBOX_API_KEY=your_api_key
```

### Create a new template definition file

Create a template file with the following content:

```python
# template.py
from ucloud_sandbox import Template, wait_for_timeout

template = (
    Template()
    .from_base_image()
    .set_envs(
        {
            "HELLO": "Hello, World!",
        }
    )
    .set_start_cmd("echo $HELLO", wait_for_timeout(5_000)))
```

### Create build script

```python
# build.py
from dotenv import load_dotenv
from ucloud_sandbox import Template, default_build_logger
from template import template

load_dotenv()

if __name__ == '__main__':
    Template.build(
        template,
        'my-template',
        cpu_count=1,
        memory_mb=1024,
        on_build_logs=default_build_logger(),
    )
```

### Build template

```bash
python build.py
```

## Create a new sandbox from a template

```python
from ucloud_sandbox import Sandbox

# Create a sandbox from a template
sandbox = Sandbox.create("my-template")
```

> The template name is an identifier that can be used to create a new sandbox.

## Build restrictions

Template building is subject to the following restrictions:

- **Max Build Time**: Builds can run for up to **1 hour**. If the build exceeds this time, it will be terminated.
- **Maximum number of vCPUs per build**: Default is 8 vCPUs, customizable for Enterprise Edition.
- **Maximum memory per build**: Default is 8 GB, customizable for Enterprise Edition.
- **Maximum disk size per build**: Default is 10 GB, customizable for Enterprise Edition.
- **Number of concurrent builds**: Default is 20, enterprise version can be customized.

If you need a higher limit, please contact customer service.

## Billing instructions

There are fees for template construction and storage. Each user enjoys **60GB free storage quota**, and the excess will be charged according to actual usage.

> For detailed billing rules, please refer to [Billing Instructions](/docs/agent-sandbox/product/fee.md).