Scripting

Knot includes a powerful scripting system based on Scriptling, a Python-like scripting language. Scripts can automate tasks, extend functionality, and be exposed as MCP tools for AI assistants.

For the complete language reference including syntax, types, control flow, functions, and classes, see the Scriptling Language Guide.


Overview

Scripts can serve multiple purposes in knot:

  • Automation: Automate space management, configuration, or deployment tasks
  • MCP Tools: Create custom tools that AI assistants can discover and execute
  • Startup/Shutdown: Define scripts that run when spaces start or stop (configured in templates)
  • Libraries: Create reusable code modules that can be imported by other scripts

Script Types

When creating a script, you specify its type:

Type Description
script Standard executable script (default)
lib Library module for import by other scripts
tool MCP tool exposed to AI assistants

Global vs User Scripts

Scripts can be either global or user-specific:

  • Global Scripts: Available to all users (with optional group restrictions). Created by administrators.
  • User Scripts: Personal scripts owned by individual users. Only visible to the owner.

User scripts with the same name override (shadow) global scripts, allowing users to customize behavior.


Creating Scripts

Via Web Interface

  1. From the menu, select Scripts, then click New Script.
  2. Fill in the required fields:
    • Name: A descriptive name to identify the script
    • Description: Brief description of what the script does
    • Type: Script type (script, lib, or tool)
    • Content: The script code
    • Active: Whether the script is enabled
  3. For MCP tools, also define:
    • Parameter Schema: TOML defining input parameters
    • Keywords: Tags for tool discovery
    • Discoverable: Whether the tool is visible to AI assistants

Via CLI

# List scripts
knot script list

# Show script details
knot script show <script-name>

# Delete a script
knot script delete <script-name>

Running Scripts

Remote Execution (in a Space)

Run scripts inside a running space:

# Run script in a space
knot space run-script <space-name> <script-name>

# With piped input
echo "data" | knot space run-script <space-name> <script-name>

Execution Environments

Knot has two embedded execution environments — one per execution location — plus a sandbox for AI-written scripts and standalone scriptling:

Environment Runs Used By System Access
Server In the knot server MCP tool scripts, event sink scripts None
Space In the space (agent) Startup/shutdown scripts, user scripts, knot run-script, health checks, knot methods register Full (container)
AI script In the knot server (sandboxed) Scripts the AI assistant writes and runs with the run_script tool None (no network, no filesystem)
External Host (scriptling-cli) Scripts outside knot using knot.zip Host
Does the script run in the knot server?
├─ YES → Server environment (MCP tools, event sinks)
└─ NO → Is it running in a space/container?
    ├─ YES → Space environment (one shared library surface for every agent-side context)
    └─ NO → External environment

Server Environment

Used by: MCP tool scripts and event sink scripts, executed inside the knot server.

The restricted environment. No system access libraries (os, pathlib, subprocess, sys), no scriptling.runtime, no knot.methods, and fs only when server.script_fs_allowed_paths is configured. Libraries are fetched from the server only (including user lib scripts). Event sinks additionally expose the knot.event accessors instead of emit(), which prevents sink → event → sink recursion.

import scriptling.mcp.tool as tool

name = tool.get_string("name", "World")
tool.return_string(f"Hello, {name}!")

Outbound network access for these scripts can also be restricted — see Network Policy.

Space Environment

Used by: every script that runs in a space under the agent — startup/shutdown scripts, user scripts (knot space run-script, eval), knot run-script (eval), health check scripts, and knot methods register. Serving and the interactive REPL run on the real Scriptling CLI in the space (Scriptling base images), not the embedded runtime.

Scripts run inside the container with full capabilities within that container’s isolation, and every agent-side context shares the same library surface (the scriptling CLI set minus container/nomad, plus all knot.* libraries including knot.methods and knot.healthcheck). All libraries are loaded on-demand from the server.

knot space run-script myspace myscript arg1 arg2

Note: Requires an active agent connection. scriptling.console and scriptling.ai.agent.interact are available for interactive sessions.

AI Script Environment

Used by: scripts the AI assistant writes and runs through the run_script tool (needs the Run AI Scripts permission).

The most restricted environment: the standard modules (less secrets and html.parser), yaml, toml, scriptling.similarity and scriptling.template.text, plus the knot.* API libraries listed in the AI column below. There is no network (requests), filesystem, system or AI access, no logging, and no user lib scripts. datetime, json, math, re, statistics, defaultdict and the allowed knot.* libraries are pre-imported, the knot libraries under their short names (knot.space as space, and knot.vars as variables); everything else, such as yaml, toml, scriptling.similarity, scriptling.template.text and the other standard modules, needs an import. All API calls go through a guarded knot.apiclient: only /api/ endpoints are allowed (so space port forwards, tunnels and knot.jobs.run are refused), a read-mode script may only read, and a deny list refuses credentials, user, group and role changes, stored script changes and more — see the full list in AI-Written Scripts.

External Environment

Used by: Standalone scriptling scripts using the knot.zip package

Scripts running outside knot entirely, using the published knot.zip package. Requires explicit configuration via knot.apiclient or environment variables — see Using knot.* Libraries for details.

scriptling --package=https://knot.example.com/packages/knot.zip myscript.py

The recommended alternative is the knot plugin: load the knot binary as a scriptling plugin and the knot.* libraries, server-stored scripts and API access all come through it with no packages or tokens to configure:

scriptling --plugin /usr/local/bin/knot knot://myscript

See Using knot.* Libraries for details.


Library Availability

Standard & Extension Libraries

Library MCP Remote AI script External
Standard Libraries ✓ ✓ ✓ ✓
requests ✓ ² ✓ ✗ ✓
secrets ✓ ✓ ✗ ✓
yaml / toml ✓ ✓ ✓ ✓
shlex ✓ ✓ ✓ ✓
fs ✓ ¹ ✓ ✗ ✓
html.parser ✓ ✓ ✗ ✓
logging ✓ ✓ ✗ ✓
subprocess ✗ ✓ ✗ ✓
os / pathlib ✗ ✓ ✗ ✓
glob ✗ ✓ ✗ ✓
tempfile ✗ ✓ ✗ ✓
shutil ✗ ✓ ✗ ✓
zipfile ✗ ✓ ✗ ✓
tarfile ✗ ✓ ✗ ✓
sys ✗ ✓ ✗ ✓

¹ On the knot server (MCP tool execution and event sink scripts) fs is only registered when the admin configures server.script_fs_allowed_paths (flag --script-fs-allowed-paths, env KNOT_SCRIPT_FS_ALLOWED_PATHS); without it, server-side scripts have no local filesystem access. In spaces (Remote) fs is always available, scoped to the container.

² On the knot server (MCP tool execution and event sink scripts), outbound requests can be restricted via a network policy; left unconfigured, they’re unrestricted. In spaces (Remote) requests is always unrestricted.

scriptling.* Libraries

Library MCP Remote AI script External
scriptling.secret Pro * ✗ ✗ ✓
scriptling.ai ✓ ¹ ✓ ✗ ✓
scriptling.ai.agent ✓ ✓ ✗ ✓
scriptling.ai.tools ✓ ✓ ✗ ✓
scriptling.ai.memory ✗ ✓ ✗ ✓
scriptling.mcp / scriptling.mcp.tool ✓ ¹ ✓ ✗ ✓
scriptling.toon ✓ ✓ ✗ ✓
scriptling.messaging (telegram / discord / slack) ✓ ✓ ✗ ✓
scriptling.oauth ✗ ✓ ✗ ✓
scriptling.mercure ✓ ¹ ✓ ✗ ✓
scriptling.grep ✗ ✓ ✗ ✓
scriptling.find ✗ ✓ ✗ ✓
scriptling.csv ✓ ✓ ✓ ✓
scriptling.xml ✓ ✓ ✓ ✓
scriptling.sed ✗ ✓ ✗ ✓
scriptling.similarity ✓ ✓ ✓ ✓
scriptling.wait_for ✗ ✓ ✗ ✓
scriptling.template.html ✓ ✓ ✗ ✓
scriptling.template.text ✓ ✓ ✓ ✓
scriptling.provision.file ✗ ✓ ✗ ✓
scriptling.provision.fetch ✗ ✓ ✗ ✓
scriptling.provision.command ✗ ✓ ³ ✗ ✓
scriptling.provision.package ✗ ✓ ³ ✗ ✓

* Requires a Pro license for secret provider access (Vault, 1Password). Standalone scriptling has built-in secret support.

¹ On the knot server (MCP tool execution and event sink scripts), outbound connections can be restricted via a network policy, same as requests above; left unconfigured, they’re unrestricted.

³ In a space the provisioning libraries can run steps as root with become=True, through sudo; see Provisioning. The scriptling CLI (External) allows it unless run with --deny-become.

knot.* Libraries

In MCP and Remote contexts the Go runtime provides the transport automatically — no configuration needed. In External contexts knot.apiclient must be configured, except when using the knot plugin where it is automatic. Most knot.* libraries are available everywhere, but a few are context-restricted — the library reference documents the exact Execution Environment for each.

Library MCP Remote AI script External
knot.space ✓ ✓ ✓ ‡ ✓
knot.user ✓ ✓ ✓ ✓
knot.group ✓ ✓ ✓ ✓
knot.role ✓ ✓ ✓ ✓
knot.template ✓ ✓ ✓ ✓
knot.vars ✓ ✓ ✓ (as variables) ✓
knot.volume ✓ ✓ ✓ ✓
knot.permission ✓ ✓ ✓ ✓
knot.stack ✓ ✓ ✓ ‡ ✓
knot.pool ✓ ✓ ✓ ✓
knot.script ✓ ✓ ✓ § ✓
knot.skill ✓ ✓ ✓ ✓
knot.slash_command ✓ ✓ ✓ ✓
knot.server ✓ ✓ ✓ ✓
knot.audit ✓ ✓ ✓ ✓
knot.files ✓ ✓ ✓ ✓
knot.files.sync ✗ ⁴ ✓ ✗ ✗
knot.jobs ✓ ✓ ✓ ‡ ✓
knot.token ✓ ✓ ✗ ✓
knot.tunnel ✓ ✓ ✓ ✓
knot.event_sink ✓ ✓ ✓ ✓
knot.mcp_server ✓ ✓ ✗ ✓
knot.ai ✓ ✓ ✗ ✓
knot.mcp ✓ ✓ ✗ ✓
knot.apiclient ✓ (automatic) ✓ (automatic) ✓ (guarded) ✓ (configure first)
knot.event emit only † emit only † ✗ emit only †
knot.methods ✗ ✓ ✗ ✗
knot.methods.schema ✗ ✓ ✗ ✗
knot.healthcheck ✗ ✓ ✗ ✗
knot.identity ✓ ✗ ✓ ✗
knot.secret Pro ✗ ⁴ ✓ ✗ in a space only ⁴
knot.plugin ✓ ✗ ✗ ✗

‡ In AI scripts the functions that call /space-io/ endpoints are refused: knot.space’s port forward and tunnel functions, knot.jobs.run, and the port forwards knot.stack.create applies. knot.stack.create is not undone when that happens: for a definition with port forwards it creates the spaces and then fails.

§ In AI scripts knot.script can read and run existing scripts only: create(), update() and delete() are refused, as the policy denies writes to /api/scripts, and so is running inline code (execute(content=...), execute_content()).

⁴ knot.secret and knot.files.sync work only inside a space, through the space’s agent; elsewhere they can be imported but their functions raise an error. knot.secret also works for Scriptling run with knot as a plugin inside a space.

† knot.event is context-sensitive: emit() is available in space scripts, MCP tool scripts, and external scripts. The payload/metadata accessors (get_string(), type(), space(), …) are only available in event sink scripts — see Events.

Event sink scripts follow the MCP column, except knot.event exposes the sink accessors instead of emit(). Plugin handlers also have the MCP column’s knot.* libraries (with emit(), knot.identity and knot.plugin), plus system access libraries — see Writing Plugins. Health check scripts run agent-side in the space and share the full Space environment, including knot.healthcheck, but without the Go knot.apiclient transport: the API libraries, knot.mcp and knot.event.emit() work there only when the space’s environment sets KNOT_API_PORT (or KNOT_URL/KNOT_TOKEN) for the Python knot.apiclient to configure itself from — see Environment Compatibility.


MCP Tools

Scripts of type tool are exposed as MCP tools for AI assistants. These tools can be discovered and executed by AI systems like Claude or ChatGPT.

Parameter Schema

Define parameters in TOML format:

requires_approval = true

[[parameters]]
name = "name"
type = "string"
description = "Name of the space"
required = true

Set requires_approval = true for tools that write, mutate, delete, start, stop, or execute commands. Knot publishes the tool as destructive (the MCP destructiveHint), so MCP clients connected to /mcp, such as Claude Desktop and Claude Code, ask before calling it. The web assistant asks before every tool call, and the user can choose Always Allow for the tool.

Set always_confirm when the user must be asked every time, with no Always Allow in the web assistant: always_confirm = true for every call, or a table of argument values for only the calls that match, such as always_confirm = { mode = "write" }. It also publishes the tool as destructive.

Parameter Types

Type Description
string Text value
number Numeric value
boolean True/false value
array List of values

Access Control

Zone Restrictions

Scripts can be limited to specific zones:

  • If no zones are specified, the script is available in all zones
  • Zones prefixed with ! are exclusions (e.g., !us-west-1 excludes that zone)

Group Restrictions

Global scripts can be restricted to specific user groups. Only users in those groups can see and execute the script.


Permissions

Permission Description
MANAGE_OWN_SCRIPTS Create, update, and delete own scripts
MANAGE_SCRIPTS Manage global scripts (admin)
EXECUTE_OWN_SCRIPTS Execute own scripts
EXECUTE_SCRIPTS Execute global scripts

What’s Next