Build Template

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)

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

Example Request

Build a Python template:

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:

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)

{
  "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

{
  "type": "RUN",
  "args": ["pip install pandas numpy"]
}

ENV Steps

{
  "type": "ENV",
  "args": ["PYTHONUNBUFFERED=1", "DEBUG=true"]
}

WORKDIR Steps

{
  "type": "WORKDIR",
  "args": ["/workspace"]
}

Errors

Alpine Not Supported (400)

{
  "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)

{
  "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)

{
  "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:

# 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

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

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"]
      }
    ]
  }'

Building Templates - Learn about template building
Template Configuration - Configure template resources
Template Caching - Optimize build performance
Get Template - Check template details after build
CLI Template Commands - Template management from CLI

Next Steps

Get Template - Check template details after build
Stream Build Logs - Monitor build progress
Create Sandbox - Use your new template

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (202 Accepted)

Response Fields

Status Codes

Build Steps

Supported Step Types

RUN Steps

ENV Steps

WORKDIR Steps

Errors

Alpine Not Supported (400)

Template Exists (409)

Invalid Resources (400)

Monitor Build Progress

Use Cases

Create Data Science Template

Update Existing Template

Next Steps

​Endpoint

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (202 Accepted)

​Response Fields

​Status Codes

​Build Steps

​Supported Step Types

​RUN Steps

​ENV Steps

​WORKDIR Steps

​Errors

​Alpine Not Supported (400)

​Template Exists (409)

​Invalid Resources (400)

​Monitor Build Progress

​Use Cases

​Create Data Science Template

​Update Existing Template

​Related

​Next Steps

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (202 Accepted)

Response Fields

Status Codes

Build Steps

Supported Step Types

RUN Steps

ENV Steps

WORKDIR Steps

Errors

Alpine Not Supported (400)

Template Exists (409)

Invalid Resources (400)

Monitor Build Progress

Use Cases

Create Data Science Template

Update Existing Template

Related

Next Steps