> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Templates

> Build custom agent runtime environments with TemplateBuilder.

Gravix Layer provides public base templates that are ready to use out of the box. You can also build your own custom templates from public Docker images.

## Public Base Templates

Pre-built templates are available in all supported regions. Built on [python:3.14-slim-bookworm](https://hub.docker.com/layers/library/python/3.14-slim-bookworm/images/sha256-db0899ae1316cd7c58e8ffcc77fbfc51b353c5848cd667c2d21d860679f73da7).

| Template                  | Resources                     | Provider / Region |
| ------------------------- | ----------------------------- | ----------------- |
| `python-3.14-base-small`  | 1 vCPU / 1 GB RAM / 2 GB disk | azure / eastus2   |
| `python-3.14-base-medium` | 1 vCPU / 2 GB RAM / 4 GB disk | azure / eastus2   |
| `python-3.14-base-large`  | 2 vCPU / 4 GB RAM / 8 GB disk | azure / eastus2   |

```python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()

# Use a public base template directly
runtime = client.runtime.create(template="python-3.14-base-small")
```

## Build a Custom Template

Custom templates let you define your own environment from any public Docker image. Currently supports Ubuntu, Alpine, and Debian based images.

```python theme={null}
from gravixlayer import GravixLayer, TemplateBuilder

client = GravixLayer()

builder = (
    TemplateBuilder("my-python-app")
    .from_image("python:3.14-slim-bookworm")
    .vcpu(2)
    .memory(512)
    .disk(4096)
    .pip_install("fastapi", "uvicorn")
)

status = client.templates.build_and_wait(builder, timeout_secs=600)
print(status.template_id)
```

## TemplateBuilder Methods

* **Base**: `from_image` or `dockerfile`
* **Build steps**: `run`, `apt_install`, `pip_install`, `npm_install`, `copy_file`, `copy_dir`, `git_clone`, `mkdir`
* **Runtime launch**: `start_cmd`
* **Readiness**: `ready_cmd` with `wait_for_port` or `wait_for_process`
* **Resources**: `vcpu`, `memory`, `disk`
* **Environment**: `env`, `envs`, `tags`

## Manage Templates

```python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()

# List templates
page = client.templates.list()
for t in page.templates:
    print(f"{t.name}: {t.description}")

# Fetch details for the first template (if any)
if page.templates:
    template_id = page.templates[0].template_id
    info = client.templates.get(template_id)
    print(info.template_id, info.status)

    # Delete the template (uncomment to actually delete)
    # client.templates.delete(template_id)
```

## Build Status Values

| Status      | Description              |
| ----------- | ------------------------ |
| `queued`    | Build is queued          |
| `building`  | Build in progress        |
| `ready`     | Template is ready to use |
| `failed`    | Build failed             |
| `cancelled` | Build was cancelled      |

<Info>
  Use `build_and_wait` for a simple blocking workflow. It starts the build and polls until the template reaches a terminal state.
</Info>