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

# Configuration

> Configure templates with resources, steps, and commands in HopX. Set vCPU, memory, and disk limits, define build steps, install packages, and configure template environments. Learn how to configure templates for optimal performance and functionality. Includes Python and JavaScript SDK examples and configuration options.

Configure templates with resources, build steps, commands, environment variables, and ready checks. Template configuration determines the final sandbox environment.

## Prerequisites

Before you begin, make sure you have:

* **Understanding of template building** - Familiarity with [Building Templates](/core-concepts/templates/building) is required
* **Template builder SDK** - Python SDK with template builder (`from hopx_ai.template import Template`)
* **Resource requirements** - Know your CPU, memory, and disk requirements
* **Build steps** - Plan your installation commands and file operations

## Overview

Template configuration includes:

* Resource specifications (CPU, memory, disk)
* Build steps (commands, file operations)
* Environment variables
* Working directories and users
* Start commands and ready checks
* Port exposure and health checks

<Note>
  Template configuration is set during template building. Once built, templates are immutable - create a new template to change configuration.
</Note>

## Resource Configuration

Configure template resources:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import BuildOptions
    import os

    # Configure resources in BuildOptions
    options = BuildOptions(
        name="my-template",
        api_key=os.getenv("HOPX_API_KEY"),
        cpu=4,              # 4 vCPU cores
        memory=4096,         # 4GB RAM
        disk_gb=20,         # 20GB disk
        context_path=os.getcwd()  # Required: Working directory
    )

    # Resource limits depend on your plan
    # Typical ranges:
    # - CPU: 1-64 cores
    # - Memory: 512MB-64GB
    # - Disk: 1GB-250GB
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const options = new BuildOptions({
      name: 'my-template',
      apiKey: process.env.HOPX_API_KEY,
      cpu: 4,              // 4 vCPU cores
      memory: 4096,        // 4GB RAM
      diskGb: 20           // 20GB disk
    });
    ```
  </Tab>
</Tabs>

## Build Steps

Configure build steps for template:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template

    template = Template()
    template.from_python_image("3.11-slim")

    # Run commands
    template.run_cmd("apt-get update")
    template.run_cmd("apt-get install -y git curl")

    # Install packages (convenience methods)
    template.apt_install("vim", "nano")
    template.pip_install("numpy", "pandas")
    template.npm_install("typescript", "tsx")

    # Set working directory
    template.set_workdir("/app")

    # Set user
    template.set_user("appuser")

    # Set environment variables
    template.set_env("NODE_ENV", "production")
    template.set_env("DEBUG", "false")

    # Copy files (requires file upload)
    # template.copy("/local/src", "/app", options=CopyOptions(owner="appuser"))
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const template = new Template('python:3.11-slim');

    // Run commands
    template.runCmd('apt-get update');
    template.runCmd('apt-get install -y git curl');

    // Install packages
    template.aptInstall('vim', 'nano');
    template.pipInstall('numpy', 'pandas');
    template.npmInstall('typescript', 'tsx');

    // Set working directory
    template.setWorkdir('/app');

    // Set user
    template.setUser('appuser');

    // Set environment variables
    template.setEnv('NODE_ENV', 'production');
    template.setEnv('DEBUG', 'false');
    ```
  </Tab>
</Tabs>

## Start Command and Ready Checks

Configure start command and ready checks:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template
    from hopx_ai.template.ready_checks import (
        wait_for_port,
        wait_for_url,
        wait_for_file,
        wait_for_process,
        wait_for_command
    )

    template = Template()
    template.from_python_image("3.11-slim")
    template.pip_install("flask", "gunicorn")

    # Start command with port ready check
    template.set_start_cmd(
        "gunicorn -w 4 -b 0.0.0.0:8000 app:app",
        ready=wait_for_port(8000, timeout=30000)
    )

    # Alternative ready checks
    # Wait for URL
    template.set_start_cmd(
        "python app.py",
        ready=wait_for_url("http://localhost:8000/health", timeout=30000)
    )

    # Wait for file
    template.set_start_cmd(
        "python app.py",
        ready=wait_for_file("/app/ready.txt", timeout=30000)
    )

    # Wait for process
    template.set_start_cmd(
        "python app.py",
        ready=wait_for_process("python", timeout=30000)
    )

    # Wait for command
    template.set_start_cmd(
        "python app.py",
        ready=wait_for_command("curl -f http://localhost:8000/health", timeout=30000)
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    import { waitForPort, waitForUrl } from '@hopx-ai/sdk';

    const template = new Template('python:3.11-slim');
    template.pipInstall('flask', 'gunicorn');

    // Start command with port ready check
    template.setStartCmd(
      'gunicorn -w 4 -b 0.0.0.0:8000 app:app',
      waitForPort(8000, { timeout: 30000 })
    );

    // Wait for URL
    template.setStartCmd(
      'python app.py',
      waitForUrl('http://localhost:8000/health', { timeout: 30000 })
    );
    ```
  </Tab>
</Tabs>

## Port Exposure

Expose ports for services:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template

    template = Template()
    template.from_python_image("3.11-slim")

    # Expose ports
    template.expose(8000)   # HTTP server
    template.expose(5432)  # PostgreSQL
    template.expose(6379)  # Redis

    # Ports are automatically exposed when sandbox is created
    # Access via: https://{port}-{sandbox_id}.{region}.vms.hopx.dev/
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const template = new Template('python:3.11-slim');

    // Expose ports
    template.expose(8000);   // HTTP server
    template.expose(5432);   // PostgreSQL
    template.expose(6379);   // Redis
    ```
  </Tab>
</Tabs>

## Complete Configuration Example

Here's a complete template configuration:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template, BuildOptions
    from hopx_ai.template.ready_checks import wait_for_port
    import os

    # Create template
    template = Template()
    template.from_python_image("3.11-slim")

    # System packages
    template.apt_install("curl", "git", "build-essential", "postgresql-client")

    # Working directory
    template.set_workdir("/app")

    # Python packages
    template.pip_install("flask", "gunicorn", "psycopg2", "redis")

    # Environment variables
    template.set_env("FLASK_ENV", "production")
    template.set_env("DATABASE_URL", "postgresql://localhost/db")
    template.set_env("REDIS_URL", "redis://localhost:6379")

    # Expose ports
    template.expose(8000)

    # Start command with ready check
    template.set_start_cmd(
        "gunicorn -w 4 -b 0.0.0.0:8000 app:app",
        ready=wait_for_port(8000, timeout=30000)
    )

    # Build with resource configuration
    options = BuildOptions(
        name="flask-production-template",
        api_key=os.getenv("HOPX_API_KEY"),
        cpu=4,
        memory=4096,
        disk_gb=20,
        context_path=os.getcwd()
    )

    result = await Template.build(template, options)
    print(f"Template configured and built: {result.template_id}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    import { Template, BuildOptions, waitForPort } from '@hopx-ai/sdk';

    const template = new Template('python:3.11-slim');

    // System packages
    template.aptInstall('curl', 'git', 'build-essential', 'postgresql-client');

    // Working directory
    template.setWorkdir('/app');

    // Python packages
    template.pipInstall('flask', 'gunicorn', 'psycopg2', 'redis');

    // Environment variables
    template.setEnv('FLASK_ENV', 'production');
    template.setEnv('DATABASE_URL', 'postgresql://localhost/db');
    template.setEnv('REDIS_URL', 'redis://localhost:6379');

    // Expose ports
    template.expose(8000);

    // Start command with ready check
    template.setStartCmd(
      'gunicorn -w 4 -b 0.0.0.0:8000 app:app',
      waitForPort(8000, { timeout: 30000 })
    );

    // Build with resource configuration
    const options = new BuildOptions({
      name: 'flask-production-template',
      apiKey: process.env.HOPX_API_KEY,
      cpu: 4,
      memory: 4096,
      diskGb: 20
    });

    const result = await Template.build(template, options);
    console.log(`Template configured and built: ${result.templateId}`);
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="1. Configure Resources First">
    Set appropriate CPU, memory, and disk based on your application requirements.
  </Step>

  <Step title="2. Order Build Steps">
    Order build steps logically: system packages → language packages → application setup.
  </Step>

  <Step title="3. Use Ready Checks">
    Always set ready checks for services that need to be ready before use.
  </Step>

  <Step title="4. Set Environment Variables">
    Configure environment variables during template build for consistency.
  </Step>

  <Step title="5. Expose Required Ports">
    Expose all ports your application needs to be accessible.
  </Step>
</Steps>

## Related

* **[Building Templates](/core-concepts/templates/building)** - Build custom templates
* **[Listing Templates](/core-concepts/templates/listing)** - List available templates
* **[Getting Template Details](/core-concepts/templates/getting-details)** - View template information
* **[Creating Sandboxes](/core-concepts/sandboxes/creating)** - Create sandboxes from templates
* [CLI Template Commands](/cli/commands/template) - Template management from CLI

## Next Steps

* Learn about [Building Templates](/core-concepts/templates/building) to create templates
* Explore [Template Caching](/core-concepts/templates/caching) for build optimization
* Review [Getting Template Details](/core-concepts/templates/getting-details) to verify configuration