knot.template

The knot.template library provides template management functions. Templates define the configuration for creating spaces.

Execution Environment

Functions

Usage

import knot.template as template

# List all templates
templates = template.list()
for t in templates:
    print(f"{t['name']}: {t['platform']}")

# Get a template
t = template.get("ubuntu")
print(t['description'])

# Get available icons
icons = template.get_icons()
print(icons)

# Validate a template spec before saving
result = template.validate("docker", job="image: ubuntu:24.04")
print(result["valid"])

# Build a spec from a unified description, then create a template from it
built = template.build_spec("nomad", {
    "image": "nginx:latest",
    "environment": [{"key": "NGINX_HOST", "value": "${{ .space.name }}"}],
    "ports": [{"host_port": 8080, "container_port": 80, "protocol": "tcp"}],
    "memory": "512M",
    "cpus": "1",
    "cpu_type": "cores",
})
template.create("nginx", job=built["job"], volumes=built["volumes"], platform="nomad")

Template Properties

list() returns summary objects containing:

• id - Template ID
• name - Template name
• description - Description
• platform - Platform (e.g., “linux/amd64”)
• active - Whether the template is active
• usage - Current usage count
• deployed - Number of deployed spaces

get() returns the full template including all of the above plus:

• job - Job definition
• volumes - Volume definitions
• is_managed - Whether managed by the system
• compute_units - Compute units quota
• storage_units - Storage units quota
• hash - Template hash
• with_terminal - Terminal access enabled
• with_vscode_tunnel - VS Code tunnel enabled
• with_code_server - Code Server enabled
• with_ssh - SSH access enabled
• with_run_command - Run command enabled
• allow_node_migration - Whether stopped spaces created from this local-container template can be reassigned to another node. Combined with health_check_auto_restart, automatic failed-node recovery is available in Knot Pro Pro
• schedule_enabled - Schedule enabled
• auto_start - Auto-start enabled
• max_uptime - Maximum uptime value
• max_uptime_unit - Maximum uptime unit
• icon_url - Icon URL
• groups - List of group IDs
• zones - List of zone names
• schedule - List of schedule day dicts (enabled, from, to)
• custom_fields - List of custom field dicts (name, description)
• health_check_type - Health check type (none, agent, tcp, http, program, or custom)
• health_check_config - Health check target, command, or custom script depending on type
• health_check_skip_ssl_verify - Skip TLS verification for HTTP health checks
• health_check_timeout - Health check timeout in seconds
• health_check_interval - Health check interval in seconds
• health_check_max_failures - Number of consecutive failures before the space is considered unhealthy
• health_check_auto_restart - Automatically restart when the health check fails. For agent, this restarts local-container and Nomad spaces when the agent stops transmitting. Combined with allow_node_migration, automatic failed-node recovery is available in Knot Pro Pro
• disable_user_activity - Whether filesystem user activity collection is disabled for spaces created from this template Pro
• ports - List of port dicts (name, port, protocol) defining the web ports exposed by spaces created from this template. These are injected as KNOT_HTTP_PORT, KNOT_HTTPS_PORT, and KNOT_TCP_PORT environment variables.

create() and update() also accept paths, either as a string or list of strings. These are appended to the template volume definition as managed paths entries.

For health_check_type="agent", no health_check_config value is required.

Validation

validate(platform, job='', volumes='') returns:

• valid - Whether the specification is valid
• errors - List of validation errors with field and message

Building Specs

build_spec(platform, spec, original_job='', original_volumes='') converts a runtime-agnostic unified spec into the platform’s native job definition (Nomad HCL or container YAML) plus volume-definition text. It’s the same conversion the UI spec wizard applies — useful when you want to assemble a template programmatically without hand-writing HCL or YAML.

spec is a dict with any of these keys (only image is required):

When original_job / original_volumes are provided, the server patches the unified spec into them field-by-field, preserving any hand-written content outside the wizard’s surface (just like the UI wizard’s “Apply”). Pass empty strings (the default) to build from scratch.

build_spec() returns:

• job - Native job definition text (HCL for Nomad, YAML for container platforms)
• volumes - Volume definition text (YAML)

Nodes

nodes(template_id) returns available placement nodes for local-container templates. Non-local-container templates return an empty list.

Node entries contain:

• node_id - Node ID
• hostname - Node hostname
• running_spaces - Number of currently running spaces on the node
• total_spaces - Total spaces assigned to the node