Managing Templates

Creating a Template

To create a new template:

1. Navigate to the Templates page via the Administration menu and select + Template.
2. Fill out the form presented:

Template Information

• Name: The name of the template, used to identify it in the system.

• Description: A description of the template, used to provide details about its purpose.

• Template Icon: Select an icon to represent the template and spaces created from it. This can be a built-in icon or a user-added icon.

Platform and Job Description

• Platform: Choose the platform to run the template: Docker, Podman, Nomad, or Manual.

  • Manual templates: Require the Knot agent to be started manually on the remote server.

• Nomad Job (HCL) or Container Specification (YAML): Provide the job description in either Nomad HCL or YAML format, depending on the selected platform. This field is not shown for Manual templates.

  Next to the label is a wand icon that opens the template spec wizard — a UI-driven builder that picks a base image from the catalog, sets memory/CPU, ports, environment variables, and bind mounts, then writes the spec for you. The wizard only enables for specs it can safely round-trip (single-task Nomad docker jobs, or any well-formed container spec); multi-task Nomad jobs disable the wizard with an explanatory tooltip.

Volume Definition

• Volume Definition (YAML): Optionally define volumes or managed host paths to be created for the space. This field is unavailable for Manual templates. In paths, ~ resolves to the server user’s home directory, absolute paths start with /, and relative paths are resolved from the agent working directory.

Resource Allocation & Scripts

• System Startup Script: An optional script to run when the space starts. This field is unavailable for Manual templates. The script must be one defined under scripts.

• System Shutdown Script: An optional script to run when the space stops. This field is unavailable for Manual templates. The script must be one defined under scripts.

• Allow stopped spaces to be migrated between nodes: Available only for local-container templates (Local Container, Docker, Podman, and Apple). When enabled, a stopped space created from the template can be reassigned to a different live node from the edit space form. In Knot Pro Pro , combining node migration with auto-restart on failure enables automatic recovery from failed nodes.

• Compute Units: The number of compute units the space will use. This is used to calculate the cost of running the space. Set to 0 for no cost.

• Storage Units: The number of storage units the space will use. This is used to calculate the cost of creating the space. Set to 0 for no cost.

• Maximum Uptime: The maximum time a space can run. Specify the time in minutes, hours, or days.

Scheduling

• Schedule: Define the days and times the space is allowed to run. Spaces running outside the schedule will be automatically stopped.
  • Auto Start: Automatically start a stopped space when its scheduled start time is reached.

Runtime Limits

• Maximum Uptime: The longest a space created from the template may run before knot stops it, regardless of activity. No Limit (the default) never stops it.

• Idle Timeout: Stop a running space after it has seen no user activity for the given time. Activity is an open terminal, SSH or web-port session (even one sitting idle — the session itself is enough), method calls, sustained CPU, and — on Pro servers — filesystem writes. Disabled by default. Starting the space again brings it back with its data intact.

  Spaces holding an exclusive pool lease are never stopped by the idle timeout or maximum uptime — the lease owns their lifecycle.

  One blind spot: a VS Code tunnel connects out to Microsoft’s tunnel service, so its traffic never crosses knot and knot can’t tell whether the tunnel is in use — leave the idle timeout off for spaces used mainly through a VS Code tunnel. (On Pro the filesystem tracking sees the edits and mostly covers it.)

Zones and Access Control

• Limit to Zones: Specify the zones where the template is available. Prefix a zone name with ! to make the template available in all zones except the specified one.

  A reserved zone name <leaf-node> is available for controlling template availability on leaf node servers:

  • <leaf-node>: The template is only shown on leaf node servers
  • !<leaf-node>: The template is excluded from leaf node servers (available only on the cluster)

Custom Fields and Features

• Ports: Ports declared for spaces created from the template. The type sets what a port is: HTTP and HTTPS ports get dev URLs (and KNOT_HTTP_PORT / KNOT_HTTPS_PORT environment variables), TCP ports are published on the host (KNOT_TCP_PORT), and Shared ports are not published anywhere; every user in the same zone can reach them through space-to-space port forwarding, addressed as user--space, which is useful for shared services like a team database or cache running in one space that many users’ spaces connect to. Shared ports never appear in the space list port menus. Every other port is forwardable by the owner only; see Space Forwarding for the addressing rules and pools.

• Port Forwards Pro : Forwards wired into every space created from the template, connected automatically when the space starts. The target is a space or pool name you own, or user--space for another user’s shared port. See Wiring Forwards into Templates.

• Custom Fields: Add optional fields to pass additional information into a space. Each field has a Variable Name, a Field Label / Description (shown on the space creation and edit forms), and a type - set with the wrench icon next to the field, shown as a badge on each row:

  • Text (default): a single-line input.
  • Password: a masked input.
  • Number: a digit-validated input, stored as a string.
  • Text area: a code editor for multi-line values, with a configurable language (text, scriptling, yaml, toml, json, markdown, or shell); scriptling gets the editor’s completions.
  • Autocomplete: a searchable box whose suggestions come from a plugin field handler (offered only when a plugin provides one); the value must be one of the suggested options.
  • Select: a dropdown whose options come from a plugin field handler or a manual list on the field; the value must be one of the options.

  Every field can also carry a Default value (set in the same wrench-icon dialog). The default is pre-filled when a space is created and applied when an API/CLI request omits the field. Clearing the pre-filled value keeps the field empty — a deliberately blank field never falls back to the default.

• Jobs: Define scheduled or manual jobs that are copied into spaces created from the template, where each space can edit or remove its own copy. Each job has a name, a shell command and an optional 5-field cron schedule; see Space Jobs.

• Features: Define the features available to the space (e.g., Visual Studio Code Tunnels). Users require the appropriate role permissions to access these features.

• Restrict to Groups: Specify the groups that can access the template. Only users in these groups can see the template and create spaces from it.

• Active: If unchecked, disables the template, preventing new spaces from being created from it.

Deleting a Template

To delete a template:

1. Select the menu item next to the template.
2. Click Delete to open a confirmation dialog.
3. Confirm the action to remove the template.

Editing a Template

Editing a template is similar to creating one:

1. Select the Edit option from the template menu.
2. Update the template details as needed.

Exporting and Importing Templates

Templates can be exported to a portable YAML format for version control, backup, or transfer between knot instances.

Export

knot template export "Ubuntu Desktop" > ubuntu.yaml

The YAML file contains the full template definition: metadata, job spec (HCL/YAML), volume definitions, schedule, custom fields, feature flags, health check configuration, and space jobs (including port definitions). Template variables (${{ .X }}) are preserved verbatim. Scripts are referenced by name (not UUID) for portability.

Import

# From a file
knot template import --file ubuntu.yaml

# From stdin
cat ubuntu.yaml | knot template import

# With a name override
knot template import --file ubuntu.yaml --name "Ubuntu Dev"

The import creates a new template on the server. Script names are resolved to IDs automatically — if a script doesn’t exist on the target server, it’s skipped with a warning.

YAML format

name: Ubuntu Desktop
description: Base Ubuntu 26.04 with dev tools
platform: nomad
icon_url: /icons/ubuntu-linux-alt.svg
active: true
compute_units: 1
features:
  with_terminal: true
  with_ssh: true
groups:
  - developers
zones:
  - zone1
max_uptime: 8
max_uptime_unit: hour
idle_timeout: 2
idle_timeout_unit: hour
startup_script: install-tools.sh
jobs:
  - name: backup
    command: knot run-script backup
    schedule: "0 2 * * *"
    enabled: true
job: |
  job "${{.space.name}}" {
    ...
  }
volumes: |
  volumes:
    - name: data
      type: csi

What’s Next

• Nomad Templates
• Local Container Templates