> ## 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.

# Template Ready Checks

> Utilities for checking template readiness before use in the HopX Python SDK. Verify templates are available and ready before creating sandboxes, check template status, and handle template availability errors. Essential for robust sandbox creation workflows. Includes code examples and error handling.

**Version:** 0.3.0\
**Last Verified:** 2025-01-27\
**Package:** `hopx-ai` on [PyPI](https://pypi.org/project/hopx-ai/)

## Overview

Ready checks are utilities used in template building to verify that a template is ready before it's considered complete. Use ready checks to ensure services are running, files exist, or commands succeed before the template is marked as ready.

## Import

```python theme={null}
from hopx_ai.template import (
    wait_for_port,
    wait_for_url,
    wait_for_file,
    wait_for_process,
    wait_for_command
)
```

## Available Ready Checks

### `wait_for_port`

Wait for a port to be listening.

```python theme={null}
wait_for_port(port, timeout=60) -> ReadyCheck
```

**Parameters:**

* `port` (`int`): Port number to check
* `timeout` (`int`, optional): Timeout in seconds (default: `60`)

**Example:**

```python theme={null}
from hopx_ai.template import Template, wait_for_port

template = (
    Template()
    .from_node_image("20")
    .expose(3000)
    .start_cmd("node server.js")
    .ready_check(wait_for_port(3000))
)
```

***

### `wait_for_url`

Wait for a URL to be accessible.

```python theme={null}
wait_for_url(url, timeout=60) -> ReadyCheck
```

**Parameters:**

* `url` (`str`): URL to check
* `timeout` (`int`, optional): Timeout in seconds

**Example:**

```python theme={null}
from hopx_ai.template import Template, wait_for_url

template = (
    Template()
    .from_python_image("3.11")
    .start_cmd("python app.py")
    .ready_check(wait_for_url("http://localhost:5000/health"))
)
```

***

### `wait_for_file`

Wait for a file to exist.

```python theme={null}
wait_for_file(path, timeout=60) -> ReadyCheck
```

**Parameters:**

* `path` (`str`): File path to check
* `timeout` (`int`, optional): Timeout in seconds

**Example:**

```python theme={null}
from hopx_ai.template import Template, wait_for_file

template = (
    Template()
    .from_python_image("3.11")
    .run("python setup.py")
    .ready_check(wait_for_file("/app/ready.flag"))
)
```

***

### `wait_for_process`

Wait for a process to be running.

```python theme={null}
wait_for_process(process_name, timeout=60) -> ReadyCheck
```

**Parameters:**

* `process_name` (`str`): Process name to check
* `timeout` (`int`, optional): Timeout in seconds

**Example:**

```python theme={null}
from hopx_ai.template import Template, wait_for_process

template = (
    Template()
    .from_python_image("3.11")
    .start_cmd("python worker.py")
    .ready_check(wait_for_process("worker.py"))
)
```

***

### `wait_for_command`

Wait for a command to succeed.

```python theme={null}
wait_for_command(command, timeout=60) -> ReadyCheck
```

**Parameters:**

* `command` (`str`): Command to execute
* `timeout` (`int`, optional): Timeout in seconds

**Example:**

```python theme={null}
from hopx_ai.template import Template, wait_for_command

template = (
    Template()
    .from_python_image("3.11")
    .run("pip install -r requirements.txt")
    .ready_check(wait_for_command("python -c 'import requests'"))
)
```

***

## Examples

### Example 1: Port Ready Check

```python theme={null}
from hopx_ai.template import Template, wait_for_port
import asyncio

async def main():
    template = (
        Template()
        .from_node_image("20")
        .run("npm install express")
        .copy("./server.js", "/app/server.js")
        .expose(3000)
        .start_cmd("node /app/server.js")
        .ready_check(wait_for_port(3000, timeout=120))
    )
    
    result = await template.build()
    print(f"Template ready: {result.template_id}")

asyncio.run(main())
```

### Example 2: URL Ready Check

```python theme={null}
from hopx_ai.template import Template, wait_for_url
import asyncio

async def main():
    template = (
        Template()
        .from_python_image("3.11")
        .run("pip install flask")
        .copy("./app.py", "/app/app.py")
        .expose(5000)
        .start_cmd("python /app/app.py")
        .ready_check(wait_for_url("http://localhost:5000/health", timeout=90))
    )
    
    result = await template.build()
    print(f"Template ready: {result.template_id}")

asyncio.run(main())
```

***

## Related Classes

* **[Template Builder](/sdk/python/template-builder)** - Use ready checks in templates
* **[Sandbox](/sdk/python/sandbox)** - Create sandboxes from templates

## See Also

* [Template Builder](/sdk/python/template-builder) - Learn about building templates
* [Core Concepts: Templates](/core-concepts/templates) - Learn about templates

## Next Steps

Now that you understand ready checks, explore:

* [Template Builder](/sdk/python/template-builder) - Use ready checks in template building
* [Building Templates](/core-concepts/templates/building) - Learn template building concepts
* [Template Configuration](/core-concepts/templates/configuration) - Configure templates
* **[CLI Reference](/cli/introduction)** - Use HopX from the command line
* [Custom Templates](/cookbooks/advanced/custom-templates) - Build custom templates