Using Templates

Templates are pre-configured sandbox environments optimized for specific workloads. They include pre-installed dependencies, tools, and configurations for fast, reliable execution.

What is a Template?

A template defines the sandbox environment where your agent runs:

• Operating system and runtime
• Pre-installed packages and tools
• System configuration
• Cached dependencies

Benefits:

• ⚡ Fast Startup: ~150ms creation time with pre-cached dependencies
• 🔒 Consistency: Same environment every time
• 🚀 Optimization: Pre-warmed for specific workloads
• 🛠️ Tools Included: Everything your agent needs, ready to go

Available Templates

Knify provides several optimized templates:

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "cursor_task",
      "prompt": "Refactor this codebase for better performance"
    }
  }'

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "fh_e2e_tools",
      "prompt": "Run the signup flow test"
    }
  }'

Template Selection

Automatic Selection

Templates are automatically chosen based on job type:

Manual Selection (Advanced)

Specify a custom template ID:

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "cursor_task",
      "prompt": "Your task",
      "template_id": "your_custom_template_id"
    }
  }'

Template Features

Pre-Installed Tools

Templates include commonly needed tools:

Cursor Agent Template:

• Git, curl, wget
• Python pip, venv
• Node.js, npm
• Text editors (vim, nano)

E2E Testing Template:

• All Cursor Agent tools
• Playwright CLI
• Browser automation utilities
• Screenshot and video recording tools

Cached Dependencies

Dependencies are pre-installed and cached:

# In E2E template, Playwright is already installed
# This command runs instantly:
pnpm install

No waiting for npm install or pip install every time.

Environment Variables

Templates support environment variable injection:

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "cursor_task",
      "prompt": "Deploy to production",
      "env": {
        "API_KEY": "your_api_key",
        "DEPLOY_ENV": "production"
      }
    }
  }'

Template Lifecycle

Creation

When a job starts:

1. Template is pulled (cached if used before)
2. Sandbox created from template (~150ms)
3. Workspace mounted (if specified)
4. Environment variables injected
5. Job execution begins

Persistence

Sandboxes created from templates persist across job continuations:

• Template configuration remains
• Installed packages persist
• System state preserved
• Files and memory retained

Updates

Templates are versioned and can be updated:

# List available templates
curl https://api.knify.io/templates \
  -H "Authorization: Bearer $KNIFY_API_KEY"

# Get template details
curl https://api.knify.io/templates/{template_id} \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Custom Templates

Want to create your own optimized template? Contact support or see the Custom Template Guide.

Use cases for custom templates:

• Specific language runtimes (Ruby, Go, Rust)
• Specialized tools (Docker, Kubernetes CLI)
• Company-specific dependencies
• Security-hardened environments
• GPU-enabled workloads

Template Requirements

Custom templates must:

• Be based on a compatible base image
• Include necessary runtimes and tools
• Support the Knify sandbox lifecycle
• Pass validation tests

Performance Optimization

Template Caching

Templates are cached at multiple levels:

1. Global Cache: Shared across all users
2. Regional Cache: Optimized for your deployment region
3. Hot Cache: Frequently used templates stay warm

Result: Sub-second sandbox creation for hot templates.

Choosing the Right Template

Match your template to your workload:

Best Practices

1. Use Standard Templates

Standard templates are optimized and well-tested:

{
  "spec": {
    "job_type": "cursor_task"
    // Template selected automatically
  }
}

2. Minimize Custom Installations

Pre-install dependencies in custom templates rather than installing at runtime:

# Slow (installs every job run)
"prompt": "First run 'pip install pandas', then analyze data"

# Fast (use Data Analysis template with pandas pre-installed)
"job_type": "data_analysis",
"prompt": "Analyze data"

3. Leverage Persistence

Packages installed in continued jobs persist:

# Job 1: Install custom tool
"prompt": "Install special-tool and configure it"

# Job 2: Use tool immediately
"prompt": "Use special-tool to process data"

4. Request Custom Templates

If you're running many jobs with the same dependencies, request a custom template for optimal performance.

Template Specifications

Cursor Agent Template

template_id: n72xh22qw0w5oncxk8vj
base_image: ubuntu:22.04
python: 3.11
node: 20.x
memory: 4GB
disk: 20GB
tools:
  - cursor-agent
  - git
  - python3-pip
  - nodejs
  - npm

E2E Testing Template

template_id: 34w72bs7866jw4y55xsv
base_image: ubuntu:22.04
python: 3.11
node: 20.x
pnpm: 10.14.0
memory: 8GB
disk: 30GB
tools:
  - cursor-agent
  - playwright
  - browserless-client
  - git

Troubleshooting

Template Not Found

If you specify a custom template that doesn't exist:

{
  "error": "Template 'invalid_template_id' not found",
  "available_templates": [...]
}

Solution: Use a standard template or verify your custom template ID.

Out of Memory

If jobs fail with memory errors, your template might be undersized:

Solution: Request a template with more memory or optimize your workload.

Missing Dependencies

If your job fails due to missing packages:

Solution:

1. Install at runtime (slow)
2. Request a custom template with pre-installed packages (fast)