Template Commands

Complete reference for managing environment templates using the ScaleBox CLI. Templates define the base images and configurations used to create sandbox environments.

Table of Contents

• Template Name Rules
• Command Overview
• Template Properties
• Command Configuration
• Usage Examples
• Permissions
• Troubleshooting

Template Name Rules

Template names are validated by the API. Use names that are 4–32 characters, only lowercase letters (a–z), numbers (0–9), hyphens (-), and underscores (_). They must start and end with an alphanumeric character, cannot start with a number or tpl-, and cannot contain consecutive separators (e.g. --, __). Certain words are reserved (e.g. admin, root, test, dev).

Invalid: My Nginx (uppercase, space), nginx (too short). Valid: my-nginx, python-data-science.

Command Overview

All template commands follow the pattern scalebox-cli template [subcommand]:

template build

Build a new template from a base template (inheritance) or from an external image (creation). Use exactly one of --base/--base-template-id, --external-image-url, or --image-file.

Flags:

Examples:

scalebox-cli template build --name "my-python-env" --base "python-base"
scalebox-cli template build --name "my-custom-python" --base "python-base" --dockerfile "./Dockerfile"
scalebox-cli template build --name "jupyter-gpu" --base "python-base" --cpu 4 --memory 8192
scalebox-cli template build --name "web-server" --base "python-base" --cmd "python app.py" --ready-cmd "curl -f http://localhost:8000/health"
scalebox-cli template build --name "my-ubuntu-app" --external-image-url "ubuntu:22.04" --cpu 2 --memory 2048
scalebox-cli template build --name "custom-jupyter" --image-file "jupyter.tar" --cpu 4 --memory 8192

template list

List all accessible templates with filtering options.

Flags:

Examples:

scalebox-cli template list
scalebox-cli template list --public
scalebox-cli template list --search "jupyter"
scalebox-cli template list --page 2 --limit 10

template get [template-id]

Get detailed information about a specific template.

Flags:

Examples:

scalebox-cli template get tpl-xmmk6trfpg6mv3h9u
scalebox-cli template get tpl-abc123def456789 --versions

template dockerfile [template-id]

Download Dockerfile template from a template.

Flags:

Examples:

scalebox-cli template dockerfile base
scalebox-cli template dockerfile tpl-abc123 --output Dockerfile.base
scalebox-cli template dockerfile base --output -

template update [template-id]

Update template metadata, resource specs, and port configurations.

Flags:

Examples:

scalebox-cli template update tpl-abc123 --name "new-name" --description "Updated description"
scalebox-cli template update tpl-abc123 --cpu 8 --memory 16384
scalebox-cli template update tpl-abc123 --ports '[{"port":8888,"name":"jupyter"}]'
scalebox-cli template update tpl-abc123 --tags "python,ml,gpu"

template delete [template-id]

Delete a template and all associated data permanently.

Flags:

Examples:

scalebox-cli template delete tpl-abc123
scalebox-cli template delete tpl-abc123 --force

template import-jobs

List or inspect template import jobs. Default: ongoing (pending/running) only. Use --all for all jobs.

Flags:

Examples:

scalebox-cli template import-jobs
scalebox-cli template import-jobs --all
scalebox-cli template import-jobs --template-id tpl-abc123
scalebox-cli template import-jobs --job-id job-xyz789

template share [template-id]

Share a private template with your account (visibility → account_shared). Only owner or admin.

Flags:

Examples:

scalebox-cli template share tpl-abc123
scalebox-cli template share tpl-abc123 --new-name "my-shared-env"

template unshare [template-id]

Make an account-shared template private again. Only owner or admin.

Examples:

scalebox-cli template unshare tpl-abc123

Template Properties

Understanding what information templates contain and what can be modified:

Command Configuration

The new command configuration system allows you to specify custom startup commands and readiness probes for your templates:

🎯 Custom Startup Commands

Without --cmd: Sandbox agent runs in foreground (blocking)

scalebox-cli template build --name "default-service" --base "python-base"

With --cmd: Sandbox agent runs in background, then custom command executes

scalebox-cli template build --name "web-server" --base "python-base" --cmd "python app.py"

🔍 Custom Readiness Probes

Default probe: HTTP GET /health on port 8888

Custom probe: Use --ready-cmd with either a plain command (treated as exec) or a JSON object with type (exec | httpGet | tcpSocket) and type-specific fields.

Types: exec — command (string or array); httpGet — port, path (optional), scheme (optional); tcpSocket — port.

# Plain command (CLI wraps as exec)
scalebox-cli template build --name "custom-probe" --base "python-base" --ready-cmd "curl -f http://localhost:8000/health"

# JSON (httpGet)
--ready-cmd '{"type":"httpGet","port":80,"path":"/health"}'

⚠️ Important Notes

• Container Lifecycle: If using --cmd, ensure your command keeps the container alive
• Multi-line Commands: Use \n to separate multiple commands in --cmd
• Dockerfile Restrictions: CMD and ENTRYPOINT instructions are not allowed in user Dockerfiles
• Command Priority: Sandbox agent always runs first, then custom commands execute

Common Usage Examples

🏗️ Building Custom Templates

Basic template build:

scalebox-cli template build --name "my-python-env" --base "python-base"

With custom Dockerfile and resources:

scalebox-cli template build --name "jupyter-gpu" --base "python-base" --dockerfile "./Dockerfile" --cpu 4 --memory 8192

With custom startup command and readiness probe:

scalebox-cli template build --name "web-server" --base "python-base" --cmd "python app.py" --ready-cmd "curl -f http://localhost:8000/health"

📋 Browse and Search Templates

List all available templates:

scalebox-cli template list

Search for Python-related templates:

scalebox-cli template list --search "python"

🔍 Template Inspection

Get detailed information about a template:

scalebox-cli template get tpl-xmmk6trfpg6mv3h9u

✏️ Template Updates

Update template metadata:

scalebox-cli template update tpl-abc123 --name "Enhanced Python ML" --description "Python environment with ML libraries"

Update resource specifications (can only increase):

scalebox-cli template update tpl-abc123 --cpu 8 --memory 16384

Update port configurations:

scalebox-cli template update tpl-abc123 --ports '[{"port":8888,"name":"jupyter"},{"port":3000,"name":"webapp"}]'

User Permissions

What you can do with your user API key:

👤 User API Key Permissions

• ✅ List public templates and own private templates
• ✅ View template details for accessible templates
• ✅ Build custom templates from base templates
• ✅ Update own private template metadata (name, description, resources)
• ❌ Cannot modify public templates

Troubleshooting

❌ "Template not found"

• Check: Verify the template ID is correct and spelled properly
• Permission: Ensure you have access to the template (public or owned by you)
• Format: Template IDs follow the format tpl-abc123def456789

❌ "Permission denied" for Updates

• Ownership: You can only update templates you own
• Public templates: Cannot modify public templates, only build from them
• Check role: Run scalebox-cli auth whoami to verify permissions