Library Reference
Knot provides several libraries in the knot.* namespace for interacting with the platform from scripts.
Available Libraries
| Library | Description |
|---|---|
knot.ai |
AI client for chat completions, embeddings, and streaming responses. |
knot.apiclient |
Transport layer used by all knot.* libraries for HTTP and AI connectivity. |
knot.audit |
Audit log search and filtering functions. |
knot.event |
Event emission in space-side scripts and payload accessors in sink scripts. |
knot.event_sink |
Manage event sinks — the webhook, script and JSON-RPC listeners for space lifecycle and custom events. |
knot.files |
File storage from scripts — read, write, list, copy, move and delete files in buckets, snapshot folders, manage the buckets, and run sync projects in a space. |
knot.group |
Group management functions for groups and their quotas. |
knot.healthcheck |
Functions for space health monitoring in agent-side health check scripts. |
knot.identity |
The authoritative requesting-user surface for plugin and tool code - a real User object with permission checks, over the gated loopback. |
knot.jobs |
Scheduled job management for spaces. |
knot.mcp |
MCP tool discovery and execution across all execution environments. |
knot.mcp_server |
Manage remote MCP servers whose tools knot exposes under a namespace. |
knot.methods |
Register JSON-RPC methods for the current space from startup scripts. |
knot.methods.schema |
Build JSON Schema fragments for method params and result definitions. |
knot.permission |
Permission constants and a function to list available permissions. |
knot.plugin |
Call plugins' declared handlers as the requesting user - in-process between plugins, over the authenticated loopback from user-created tools. |
knot.pool |
Manage space pools that keep a desired count of identical spaces running. |
knot.role |
Role management functions for creating roles and assigning permissions. |
knot.script |
Script management and execution functions for stored and inline scripts. |
knot.secret |
Read the space owner's personal 1Password secrets from scripts running inside a space. |
knot.server |
Server-wide information (version, wildcard and tunnel domains, space web port hosts), cluster nodes, loaded plugins and a search across everything you may see. |
knot.skill |
Manage skills — markdown knowledge base content for AI agents. |
knot.slash_command |
Manage slash commands — reusable prompt templates invoked from the AI chat. |
knot.space |
Space management functions for creating, running, and editing spaces. |
knot.stack |
Stack template management and stack lifecycle functions. |
knot.template |
Template management functions for space configuration definitions. |
knot.token |
Manage API tokens — mint scoped keys, list them, revoke them. |
knot.tunnel |
List and close your tunnels, and read the tunnel server settings. |
knot.user |
User management functions including permissions, quotas, and SSH keys. |
knot.vars |
Template variable management functions including protected variables. |
knot.volume |
Volume management functions for the volume definitions attached to spaces. |
Scriptling libraries
The full scriptling.* library set is documented on the Scriptling website, including:
scriptling.grep— fast file content searchscriptling.find— find files by name, type, mtime, and sizescriptling.net.resolve— DNS resolution for IP, SRV, and srv+http URLsscriptling.provision.file— idempotent file provisioningscriptling.provision.fetch— download files and unpack zip archives over HTTP/HTTPSscriptling.provision.command— run commands, as the space’s user or as rootscriptling.provision.package— install packages with apt, dnf, yum, apk or Homebrewscriptling.mercure— publish to and subscribe at Mercure hubs
Standard Python-compatible libraries (os, pathlib, glob, tempfile, shutil, shlex, subprocess, re, json, time, etc.) are also available — see the Scriptling library reference for the full list. Availability varies by execution environment; see Library Availability for details.
Usage
Import libraries using standard Python import syntax:
import knot.space as space
import knot.ai as ai
import knot.mcp as mcp
# Use the libraries
spaces = space.list()
client = ai.Client()
tools = mcp.list_tools()Environment Compatibility
Each library’s availability depends on where the script runs. Not every library is available in every context — most notably, MCP tool execution, event sink and plugin handler environments do not provide knot.methods, and MCP tool and event sink environments have no system access libraries. Every reference page opens with an Execution Environment table showing exactly where that library works.
Summary of the embedded execution contexts:
- MCP tool execution, event sink scripts, plugin handlers, remote/space scripts, and
knot run-scriptregister the Go-providedknot.apiclienttransport, so the API libraries (knot.space,knot.user,knot.group,knot.role,knot.audit,knot.files,knot.permission,knot.vars,knot.volume,knot.script,knot.skill,knot.slash_command,knot.server,knot.template,knot.stack,knot.pool,knot.jobs,knot.token,knot.tunnel,knot.event_sink,knot.mcp_server), plusknot.aiandknot.mcp, are available and authenticated automatically. knot.methods/knot.methods.schemaare agent-side only: remote/space scripts,knot run-script, andknot methods register. They are not available in MCP tool execution, event sink scripts or plugin handlers.knot.eventis context-sensitive:emit()runs in space-side scripts, MCP tool execution, plugin handlers, and external standalone scripts; the payload/metadata accessors run only in event sink scripts, whereemit()is not available.knot.healthcheckruns in every agent-side (space) script — health check scripts, startup scripts,knot run-script— but not in MCP tool execution, event sink scripts or plugin handlers.knot.secretPro runs only inside a space — agent-side scripts,knot run-script, and Scriptling using Knot as a plugin in a space — reading the space owner’s personal secrets through the space’s agent. Everywhere elseget()raises an error.knot.files.syncruns only inside a space — startup and shutdown scripts,knot space run-scriptandknot run-script— starting and stopping sync projects in the space’s agent. Everywhere else its functions raise an error.knot.identityandknot.pluginare server-side only: MCP tool execution, event sink scripts and plugin handlers.knot.identityis also available in AI scripts.- AI scripts (the
run_scripttool) get a sandbox with no network, filesystem or AI access. Theirknot.apiclientis a guarded transport that only allows/api/endpoints, and they may importknot.identityplus the API librariesknot.audit,knot.event_sink,knot.files,knot.group,knot.jobs,knot.permission,knot.pool,knot.role,knot.script,knot.server,knot.skill,knot.slash_command,knot.space,knot.stack,knot.template,knot.tunnel,knot.user,knot.vars(pre-imported asvariables) andknot.volume. Not available there:knot.ai,knot.mcp,knot.event,knot.secret,knot.token,knot.mcp_server,knot.methods,knot.healthcheck,knot.pluginandknot.files.sync. Functions that call/space-io/endpoints (space port forwards and tunnels,knot.jobs.run, the port forwardsknot.stack.createapplies) are refused;knot.stack.createfor a definition with port forwards creates the spaces and then fails.knot.scriptcan only read and run existing scripts there:create(),update(),delete()and running inline code are refused, as is everything else on the deny list — see the full list in AI-Written Scripts. - Health check scripts run agent-side in the space and share the full Space environment, but without the Go
knot.apiclienttransport. The API libraries,knot.mcpandknot.event.emit()fall back to the Pythonknot.apiclient, which configures itself from the agent’s/connectendpoint when the space’s environment setsKNOT_API_PORT(acting as the space owner), or fromKNOT_URL/KNOT_TOKEN; with neither, their calls raise.knot.ai’sClient()always raises there.
For standalone scripts running outside knot (the scriptling CLI), the Python implementations resolve over HTTP via knot.apiclient configuration (knot.event.emit() included); knot.methods, the knot.event sink accessors, knot.healthcheck, knot.files.sync, knot.identity and knot.plugin have no standalone form.
Authentication
Scripts automatically authenticate using the context they’re running in — no explicit token handling is needed. The knot.apiclient transport is pre-configured by the runtime.