# Build Templates

<subtitle>Execute template builds and monitor build progress and status.</subtitle>

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

>
> Before calling `Template.build(...)`, please define the `template` variable first, see: [Defining Templates](/docs/agent-sandbox/template/07-defining-template)

## Build and Wait for Completion

The `build` method will build the template and wait for completion, returning build information (including template ID and build ID).

```python
from ucloud_sandbox import Template, default_build_logger

build_info = Template.build(
    template,
    alias="my-template",  # Template alias (required)
    cpu_count=2,  # CPU core count
    memory_mb=2048,  # Memory (MB)
    skip_cache=False,  # Whether to skip cache (except file copy steps)
    on_build_logs=default_build_logger(),  # Log callback: receives LogEntry objects
    api_key="your-api-key",  # Override API key
    domain="your-domain",  # Override domain
)

# build_info contains: BuildInfo(alias, template_id, build_id)
```

## Background Build

The `build_in_background` method will start the build and return immediately (without waiting for completion), suitable for scenarios like "trigger build → poll status/pull logs later".

```python
from ucloud_sandbox import Template

build_info = Template.build_in_background(
    template,
    alias="my-template",
    cpu_count=2,
    memory_mb=2048,
)

# Returns immediately: BuildInfo(alias, template_id, build_id)
```

## Check Build Status

Use `get_build_status` to check the build status started by `build_in_background`.

```python
from ucloud_sandbox import Template

status = Template.get_build_status(
    build_info,
    logs_offset=0,  # Optional: offset for getting logs
)

# status contains build status and logs
```

## Example: Background Build with Status Polling

```python
import time
from ucloud_sandbox import Template

# Start build in background
build_info = Template.build_in_background(
    template,
    alias="my-template",
    cpu_count=2,
    memory_mb=2048,
)

# Poll build status
logs_offset = 0
status = "building"

while status == "building":
    build_status = Template.get_build_status(
        build_info,
        logs_offset=logs_offset,
    )

    logs_offset += len(build_status.log_entries)
    status = build_status.status.value

    for log_entry in build_status.log_entries:
        print(log_entry)

    # Wait a short time before checking status again
    time.sleep(2)

if status == "ready":
    print("Build completed successfully")
else:
    print("Build failed")
```