Managing Templates

Creating a Template

To create a new template:

1. Navigate to the Templates page under the Build menu and select New 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: Manual, Nomad, Local Container (or a specific container runtime: Docker, Podman, or Apple), or KVM. Only the platforms the server offers are shown.

  • Manual templates: Require the Knot agent to be started manually on the remote server.
  • Local Container: Runs on whichever container runtime the node uses; pick Docker, Podman, or Apple from the same control to tie the template to one runtime.

• 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.

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.
  • Masked: hides the value while typing; it is stored like any other value, so it is not a secret.
  • Number: a digit-validated input, stored as a string.
  • Bool: a true/false value.
  • 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.

  All values are stored as strings. On the space form, text typed into an autocomplete box matches an option’s value or label case-insensitively; if nothing matches, it is tried again with leading and trailing decoration (such as # or []) removed, so a pasted #1234 or [1234] finds the 1234 option. The API itself only accepts the exact option values.

  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.

  In the same dialog, Field Required stops a space being created or saved with the field blank (the API rejects it too); required fields are marked with an asterisk on the space forms. Always Show When Creating a Space puts an optional field on the create form next to the required ones (rows with it set show a shown badge); the toggle is disabled for required fields, which are always shown. Other optional fields wait behind a Show N more field(s) toggle on the create form, so a field used now and then stays out of the way but is one click from view. The edit form always shows every field.

  Use the up and down arrows on each row, or drag a row by its handle, to set the order the fields appear in on the space forms.

  Changing a field’s name, label, type, options, default or required setting, or the order of the fields, changes the template, so running spaces created from it show an Update Available badge. Always Show When Creating a Space only changes the create form’s layout, so it doesn’t.

  

  

• 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.

  Two switches turn features off for the template’s spaces. Each takes effect straight away for running spaces, and only covers requests made with the space’s own credentials, such as knot inside the space; a user who copies their own API token into a space isn’t blocked, and they keep access from the web interface and their own machine:

  • Disable File Storage: refuses file storage from the spaces, including knot file and the files API.
  • Disable Personal Secrets Pro : refuses reading the owner’s personal secrets, so knot secret get and knot.secret.get() fail in the spaces. It covers only the token on the user’s profile, not 1Password tools the user runs in the space themselves.

• 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 and import are admin functions: they need a token with the Manage Templates permission, and the commands live under knot admin template. Any user can still see what is available with knot template list.

Export

knot admin 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 admin template import --file ubuntu.yaml

# From stdin
cat ubuntu.yaml | knot admin template import

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

The import creates the template, or updates the existing template with the same name — use --name to import a copy alongside it. Script names are resolved to IDs automatically; a startup or shutdown script that doesn’t exist on the target server is silently dropped from the template.

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
custom_fields:
  - name: TICKET
    description: Ticket reference
    required: true
  - name: SIZE
    description: Instance size
    type: select
    options: [small, medium, large]
    default: medium
    show_on_create: true
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