Caching

Optimize template builds with caching strategies. Template caching speeds up builds by reusing layers and steps that haven’t changed.

Overview

Template caching helps you:

Speed up template builds
Reduce build costs
Reuse unchanged layers
Optimize build performance

Template builds use Docker layer caching. Steps that haven’t changed are cached and reused, significantly speeding up rebuilds.

How Caching Works

Template builds cache each step:

Python
JavaScript

from hopx_ai.template import Template

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

# These steps are cached if unchanged
template.apt_install("curl", "git")      # Cached if packages unchanged
template.pip_install("numpy", "pandas")  # Cached if packages unchanged
template.set_env("DEBUG", "true")        # Cached if value unchanged

# Only changed steps are rebuilt
template.pip_install("matplotlib")       # Only this step rebuilds if added

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

// These steps are cached if unchanged
template.aptInstall('curl', 'git');      // Cached if packages unchanged
template.pipInstall('numpy', 'pandas');  // Cached if packages unchanged
template.setEnv('DEBUG', 'true');        // Cached if value unchanged

// Only changed steps are rebuilt
template.pipInstall('matplotlib');       // Only this step rebuilds if added

Skip Cache for Steps

Skip caching for specific steps:

Python
JavaScript

from hopx_ai.template import Template

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

# Install packages (cached)
template.pip_install("numpy", "pandas")

# Run command that should always execute (skip cache)
template.run_cmd("git clone https://github.com/user/repo.git /app")
template.skip_cache()  # Skip cache for previous step

# Next steps are cached again
template.pip_install("flask")

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

// Install packages (cached)
template.pipInstall('numpy', 'pandas');

// Run command that should always execute (skip cache)
template.runCmd('git clone https://github.com/user/repo.git /app');
template.skipCache();  // Skip cache for previous step

// Next steps are cached again
template.pipInstall('flask');

Skip Cache for Entire Build

Skip all caching for a build:

Python
JavaScript

from hopx_ai.template import BuildOptions
import os

# Skip all caching
options = BuildOptions(
    name="my-template",
    api_key=os.getenv("HOPX_API_KEY"),
    skip_cache=True  # Skip all caching
)

# Useful for:
# - Debugging build issues
# - Ensuring fresh builds
# - Testing build steps

// Conceptual example
const options = new BuildOptions({
  name: 'my-template',
  apiKey: process.env.HOPX_API_KEY,
  skipCache: true  // Skip all caching
});

Optimizing Build Order

Order steps for optimal caching:

Python
JavaScript

from hopx_ai.template import Template

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

# ✅ Good: Stable steps first (cached longer)
template.apt_install("curl", "git")           # Rarely changes
template.pip_install("numpy", "pandas")        # Changes less frequently
template.set_env("NODE_ENV", "production")    # Rarely changes

# ✅ Good: Frequently changing steps last
template.run_cmd("git clone repo /app")       # Changes often
template.run_cmd("cp config.json /app")       # Changes often

# ❌ Bad: Frequently changing steps first
# template.run_cmd("git clone repo /app")     # Invalidates all cache
# template.apt_install("curl")                # Never cached

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

// ✅ Good: Stable steps first (cached longer)
template.aptInstall('curl', 'git');           // Rarely changes
template.pipInstall('numpy', 'pandas');       // Changes less frequently
template.setEnv('NODE_ENV', 'production');   // Rarely changes

// ✅ Good: Frequently changing steps last
template.runCmd('git clone repo /app');       // Changes often
template.runCmd('cp config.json /app');       // Changes often

Cache Invalidation

Understand when cache is invalidated:

Python
JavaScript

from hopx_ai.template import Template

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

# Cache is invalidated when:
# 1. Step arguments change
template.pip_install("numpy", "pandas")  # Cached
template.pip_install("numpy", "pandas", "matplotlib")  # Cache invalidated

# 2. Step order changes
template.apt_install("curl")
template.pip_install("numpy")
# vs
template.pip_install("numpy")
template.apt_install("curl")  # Different cache key

# 3. Base image changes
template = create_template("python:3.11-slim")  # One cache
template = create_template("python:3.12-slim")  # Different cache

# 4. Files change (for COPY steps)
# template.copy("/local/src", "/app")  # Cache invalidated if files change

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

// Cache is invalidated when:
// 1. Step arguments change
template.pipInstall('numpy', 'pandas');  // Cached
template.pipInstall('numpy', 'pandas', 'matplotlib');  // Cache invalidated

// 2. Step order changes
template.aptInstall('curl');
template.pipInstall('numpy');
// vs
template.pipInstall('numpy');
template.aptInstall('curl');  // Different cache key

// 3. Base image changes
const template1 = new Template('python:3.11-slim');  // One cache
const template2 = new Template('python:3.12-slim');  // Different cache

Best Practices

1. Order Steps by Stability

Place stable steps (system packages, language packages) before frequently changing steps (file copies, git clones).

2. Group Related Steps

Group related steps together to maximize cache hits.

3. Use skip_cache Sparingly

Only skip cache for steps that must always execute (e.g., git clones with latest changes).

4. Minimize Changes

Minimize changes to early steps to preserve cache for later steps.

5. Test Cache Behavior

Test builds to understand cache behavior and optimize step ordering.

Building Templates - Create templates with caching
Template Configuration - Configure template resources
Getting Template Details - View template information
CLI Template Commands - Template management from CLI

Next Steps

Learn about Building Templates to create templates
Explore Template Configuration for advanced setup
Review Listing Templates to see your templates

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

How Caching Works

Skip Cache for Steps

Skip Cache for Entire Build

Optimizing Build Order

Cache Invalidation

Best Practices

Next Steps

​Overview

​How Caching Works

​Skip Cache for Steps

​Skip Cache for Entire Build

​Optimizing Build Order

​Cache Invalidation

​Best Practices

​Related

​Next Steps

Overview

How Caching Works

Skip Cache for Steps

Skip Cache for Entire Build

Optimizing Build Order

Cache Invalidation

Best Practices

Related

Next Steps