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")

Custom fields

create() and update() take custom_fields, a list of field definitions. The list order is the order the space forms show the fields in, so reordering is just passing the list in a new order (update() replaces the whole list).

template.update("nginx", custom_fields=[
    # Required: always shown, and a space can't be created with it blank.
    {"name": "site", "description": "Site name", "required": True},
    # Optional, but shown on the create form with the required fields.
    {"name": "branch", "description": "Git branch", "default": "main", "show_on_create": True},
    # Optional and seldom needed: behind the create form's optional fields toggle.
    {"name": "seed", "description": "Database seed", "type": "textarea", "language": "yaml"},
])

Each definition takes name, description, type (text, masked, number, bool, select, autocomplete or textarea), handler or options (select and autocomplete, exactly one), language (textarea), default, required and show_on_create. show_on_create only affects how the create form is laid out and is ignored on required fields; the edit form always shows every field.

Template Properties

list() returns summary objects containing:

• id - Template ID
• name - Template name
• description - Description
• platform - Platform: docker, podman, apple, container (local container, backend chosen automatically), nomad, kvm, or manual
• active - Whether the template is active
• usage - Current usage count
• deployed - Number of deployed spaces
• custom_fields - Custom field definitions (as described for get() below)

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
• with_vnc - VNC (web desktop) 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
• kvm_network_mode - KVM templates only: bridged (static IPs from the template’s range) or nat (libvirt NAT, DHCP) — see the VM specification
• kvm_network_cidr, kvm_ip_range_start, kvm_ip_range_end, kvm_gateway, kvm_bridge - KVM bridged network configuration derived from the template’s network: block. The IP range is empty when the template uses the network’s whole usable address space (the default when no range is set)
• runtime_available - Whether any node in the zone currently offers the runtime this template needs (always true for manual and Nomad templates)
• schedule_enabled - Schedule enabled
• auto_start - Auto-start enabled
• max_uptime - Maximum uptime value
• max_uptime_unit - Maximum uptime unit
• idle_timeout - Idle timeout value; the space is stopped after this long without user activity (terminal input, SSH or web-port traffic, method calls, sustained CPU, and on Pro filesystem writes)
• idle_timeout_unit - Idle timeout 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, type (text, masked, number, bool, textarea, select or autocomplete), required, show_on_create (when set: an optional field shown on the create-space form without opening its optional fields toggle), default (when set), and the option source — options (the manual list, also the resolved values when get ran with resolve_options=True) or handler (a plugin field handler id). These are the definitions to fill when creating a space: required fields must be set, and select/autocomplete values must be one of the field’s options (see space.create).
• 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
• disable_file_storage - Whether file storage is refused from spaces created from this template
• disable_user_secrets - Whether personal secrets are refused from 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 Arguments

create() and update() take the same keyword arguments. With create() unset arguments use the defaults below; with update() every argument defaults to None, meaning “keep the current value”. Lists passed to update() replace the whole list.

get() does not return jobs or port_forwards; update() preserves them unless you pass new lists.

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