knot knot

Managing a Space

This guide explains how to create, start, stop, update, edit, and delete spaces in Knot.

Creating a Space

  1. Navigate to the Spaces page and click the + Space button to get a list of the available templates, then select the required template. When only one template is available to you, the list is skipped and the form opens straight away.

Select a Template
2. The form starts with just what a new space needs:

  • Name: The name of the space. A name based on the template’s is filled in, numbered if you already have a space by that name; change it as you like.
  • Custom Fields: The fields the template requires (marked with an asterisk) and any optional ones it chooses to show. The template’s other optional fields are behind a toggle in the same section, shown as Show 2 more fields; opening it adds them below the toggle.
  • IP Address: For bridged KVM templates, the virtual machine’s static IP.
  • Start Space on Create: If checked, the space will start automatically after creation.

Everything else has sensible defaults and sits behind More options, and can be changed later by editing the space:

  • Description: (Optional) A description for the space.
  • Icon: (Optional) An icon for the space. By default, the template’s icon will be used if one is set.
  • Stack: (Optional) Group the space with others under a stack name.
  • Additional Space Names: Add additional names for the space by clicking the + icon. This is useful for accessing the space under multiple domain names when using the web proxy service. Each additional name can be assigned a specific HTTP port from the dropdown; the first available port is selected by default.
  • Terminal Shell: The shell to use for the terminal. By default, the user’s profile shell is used.
  • Node: Where the space runs, when there is a choice; by default the least loaded node is picked.
  • User Startup Script: An optional script to run when the space starts, the user startup script is run after the system startup script. This field is unavailable for Manual templates. The script must be one defined under scripts and owned by the user creating the space.
  • Depends On: (Optional) Select spaces that this space depends on. Dependent spaces will need to be started before this space starts.
Create Space Form
Custom Fields When Creating a Space
  1. Click Create Space to finalize the process.

Admins may see the Create Space For option, allowing them to create spaces on behalf of other users. Selecting this option will prompt for the user under whom the space will be created.

Starting a Space

  1. Navigate to the Spaces page.
  2. Click the menu icon next to the space and select Start.
  • The space’s status will change to Starting, and once running, it will display as Running.
  • Icons will appear in the services column, providing access to features such as the web terminal.

Service Icons:

  1. VNC: Opens a new window connecting to a VNC server running within the space.
  2. Code Server: Opens a new window running Code Server.
  3. VSCode Tunnel: Displays a red icon if the VSCode tunnel is not configured. When functioning, it matches the other icons. Clicking it opens a web terminal connected to the VSCode tunnel service.
  4. Web Terminal: Provides shell access to the space via a web-based terminal.
  5. Ports: Displays a menu of web interfaces and exposed ports for the space.
  • Not all icons will be present. Their availability depends on the features enabled in the template and the user’s permissions.
  • Spaces created from manual templates do not have a Start option. They start automatically when their agent connects to the server.

Resource Usage

A running space shows small CPU and memory bars on the Spaces page. Click either one to open its usage, with current figures and a history.

  • CPU is the share of the CPU the space may use: its CPU limit, or every CPU it can run on when it has none. The cores it’s using are shown alongside, such as 13.3% · 2.0 cores, and hovering over the bar in the list shows them too.
  • Memory is the space’s own memory use against its memory limit, or against the machine’s memory when it has none.
  • Disk is the disk the space uses. When the space has a disk of its own, such as a VM or a dedicated volume, it’s shown against that disk’s size. When its home is on the host’s disk, as in most containers, it’s the size of the home directory, with no limit.

The history shows the last hour per minute, or the last 7 days. CPU and memory are drawn as a percentage of their limits. Disk is drawn the same way when it has a limit; without one, it’s drawn as the space used, on its own axis on the right.

Space Usage and History

Stopping a Space

  1. Click the menu icon next to the running space.
  2. Select Stop.
Space Actions Menu
  • The Stop button is a split button:
    • Stop: Stops the space.
    • Restart: Stops and then restarts the space.

Stopping a space will result in the loss of all data in memory that is not stored on a persistent volume. However, volumes used by the space will not be deleted.

Updates

If the template used by a running space is updated, an Update Available badge will appear:

To apply the update:

  1. Stop the space.
  2. Start it again.
  • Any volumes added to the template will be created when the space starts.
  • Any volumes removed from the template will be deleted, along with their data.

Editing a Space

  1. Select Edit from the space’s menu.
  2. Update the space’s details, such as its name, icon, or additional names.
  • Additional URLs are supported immediately after the space is successfully saved.

Deleting a Space

Deleting a space will permanently delete its volumes and all associated data.

  1. Ensure the space is stopped. Only stopped spaces can be deleted.
  2. Select Delete from the space’s menu.
  3. Confirm the action in the dialog that appears.
  • When a space is deleted, all resources are freed, and all volumes and their data are removed.