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

# Build Template

> Create a custom template from a Docker image with build steps using the HopX Control Plane API. Build custom sandbox templates with specific configurations, dependencies, and resources. Learn how to use POST /v1/templates/build endpoint to create templates from Docker images. Includes request examples and template configuration.

Build a custom template from a Docker image. Define the base image, build steps, resources, and ready checks. The API will build and cache your template for creating sandboxes.

## Endpoint

```
POST /v1/templates/build
```

## Request

### Headers

```
Authorization: Bearer $HOPX_API_KEY
Content-Type: application/json
```

### Body Parameters

| Parameter              | Type    | Required | Description                                                  |
| ---------------------- | ------- | -------- | ------------------------------------------------------------ |
| `name`                 | string  | Yes      | Unique template name                                         |
| `from_image`           | string  | Yes      | Base Docker image (e.g., `ubuntu:22.04`, `python:3.11-slim`) |
| `cpu`                  | integer | Yes      | Number of vCPUs (min/max from your plan)                     |
| `memory`               | integer | Yes      | Memory in MB (min: 512, max: 64000)                          |
| `diskGB`               | integer | Yes      | Disk size in GB (min: 1, max: 250)                           |
| `steps`                | array   | No       | Build steps (RUN, COPY, ENV, WORKDIR, USER, CMD)             |
| `startCmd`             | string  | No       | Command to run on sandbox start                              |
| `readyCmd`             | object  | No       | Ready check configuration                                    |
| `skipCache`            | boolean | No       | Skip build cache (default: false)                            |
| `registry_credentials` | object  | No       | Private registry authentication                              |
| `update`               | boolean | No       | Update existing template (default: false)                    |

<Note>
  **Alpine Linux is not supported.** Use glibc-based images like `ubuntu:*`, `debian:*`, `python:*-slim`, `node:*-slim`.
</Note>

### Example Request

Build a Python template:

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/templates/build \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-python-template",
    "from_image": "python:3.11-slim",
    "cpu": 2,
    "memory": 4096,
    "diskGB": 10,
    "steps": [
      {
        "type": "RUN",
        "args": ["pip install pandas numpy matplotlib"]
      },
      {
        "type": "WORKDIR",
        "args": ["/workspace"]
      },
      {
        "type": "ENV",
        "args": ["PYTHONUNBUFFERED=1"]
      }
    ]
  }'
```

Build a Node.js template:

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/templates/build \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-nodejs-template",
    "from_image": "node:18-slim",
    "cpu": 1,
    "memory": 2048,
    "diskGB": 5,
    "steps": [
      {
        "type": "RUN",
        "args": ["npm install -g typescript ts-node"]
      },
      {
        "type": "WORKDIR",
        "args": ["/app"]
      }
    ]
  }'
```

## Response

### Success (202 Accepted)

```json theme={null}
{
  "build_id": "build_abc123",
  "template_id": "template_xyz789",
  "status": "building",
  "logs_url": "https://api.hopx.dev/v1/templates/build/build_abc123/logs",
  "request_id": "req_abc123"
}
```

### Response Fields

| Field         | Type   | Description                                   |
| ------------- | ------ | --------------------------------------------- |
| `build_id`    | string | Build ID (same as template\_id)               |
| `template_id` | string | Template ID                                   |
| `status`      | string | Build status (`building`, `active`, `failed`) |
| `logs_url`    | string | URL to stream build logs                      |
| `request_id`  | string | Request ID for debugging                      |

## Status Codes

| Code  | Description                                       |
| ----- | ------------------------------------------------- |
| `202` | Build triggered (accepted)                        |
| `400` | Invalid request (Alpine, invalid resources, etc.) |
| `401` | Authentication required                           |
| `404` | Template not found (when `update=true`)           |
| `409` | Template exists (when `update=false`)             |
| `503` | Service unavailable (no available nodes)          |

## Build Steps

### Supported Step Types

| Type      | Description                       | Example                                                        |
| --------- | --------------------------------- | -------------------------------------------------------------- |
| `RUN`     | Run a shell command               | `{"type": "RUN", "args": ["apt-get update"]}`                  |
| `COPY`    | Copy files (requires file upload) | `{"type": "COPY", "args": ["/app"], "filesHash": "sha256..."}` |
| `ENV`     | Set environment variable          | `{"type": "ENV", "args": ["KEY=value"]}`                       |
| `WORKDIR` | Set working directory             | `{"type": "WORKDIR", "args": ["/workspace"]}`                  |
| `USER`    | Set user                          | `{"type": "USER", "args": ["1000"]}`                           |
| `CMD`     | Set default command               | `{"type": "CMD", "args": ["python", "app.py"]}`                |

### RUN Steps

```json theme={null}
{
  "type": "RUN",
  "args": ["pip install pandas numpy"]
}
```

### ENV Steps

```json theme={null}
{
  "type": "ENV",
  "args": ["PYTHONUNBUFFERED=1", "DEBUG=true"]
}
```

### WORKDIR Steps

```json theme={null}
{
  "type": "WORKDIR",
  "args": ["/workspace"]
}
```

## Errors

### Alpine Not Supported (400)

```json theme={null}
{
  "error": "Alpine Linux is not supported. Use glibc-based images like ubuntu, debian, python-slim, node-slim",
  "code": "INVALID_REQUEST",
  "request_id": "req_abc123"
}
```

**Cause:** The base image is Alpine Linux, which is not supported.

**Fix:** Use a glibc-based image like `ubuntu:22.04`, `python:3.11-slim`, or `node:18-slim`.

### Template Exists (409)

```json theme={null}
{
  "error": "Template already exists. Set update=true to update it.",
  "code": "CONFLICT",
  "request_id": "req_abc123"
}
```

**Cause:** A template with the same name already exists and `update` is false.

**Fix:** Either:

* Use a different template name
* Set `"update": true` to update the existing template

### Invalid Resources (400)

```json theme={null}
{
  "error": "Invalid memory: must be between 512 and 64000 MB",
  "code": "INVALID_REQUEST",
  "request_id": "req_abc123"
}
```

**Cause:** Resource values are outside allowed limits.

**Fix:** Ensure:

* `cpu`: 1-8 (depends on your plan)
* `memory`: 512-64000 MB
* `diskGB`: 1-250 GB

## Monitor Build Progress

After triggering a build, monitor its progress:

```bash theme={null}
# Get build status
curl https://api.hopx.dev/v1/templates/build/build_abc123/status \
  -H "Authorization: Bearer $HOPX_API_KEY"

# Stream build logs
curl https://api.hopx.dev/v1/templates/build/build_abc123/logs \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

## Use Cases

### Create Data Science Template

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/templates/build \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "from_image": "python:3.11-slim",
    "cpu": 4,
    "memory": 8192,
    "diskGB": 20,
    "steps": [
      {
        "type": "RUN",
        "args": ["pip install pandas numpy matplotlib scikit-learn jupyter"]
      },
      {
        "type": "WORKDIR",
        "args": ["/workspace"]
      },
      {
        "type": "ENV",
        "args": ["PYTHONUNBUFFERED=1"]
      }
    ]
  }'
```

### Update Existing Template

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/templates/build \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-template",
    "from_image": "python:3.11-slim",
    "cpu": 2,
    "memory": 4096,
    "diskGB": 10,
    "update": true,
    "steps": [
      {
        "type": "RUN",
        "args": ["pip install --upgrade pandas"]
      }
    ]
  }'
```

## Related

* **[Building Templates](/core-concepts/templates/building)** - Learn about template building
* **[Template Configuration](/core-concepts/templates/configuration)** - Configure template resources
* **[Template Caching](/core-concepts/templates/caching)** - Optimize build performance
* **[Get Template](/api/control-plane/get-template)** - Check template details after build
* [CLI Template Commands](/cli/commands/template) - Template management from CLI

## Next Steps

* **[Get Template](/api/control-plane/get-template)** - Check template details after build
* **[Stream Build Logs](/api/control-plane/stream-logs)** - Monitor build progress
* **[Create Sandbox](/api/control-plane/create-sandbox)** - Use your new template