Library Reference

Knot provides several libraries in the knot.* namespace for interacting with the platform from scripts.


Available Libraries

LibraryDescription
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:

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-script register the Go-provided knot.apiclient transport, 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), plus knot.ai and knot.mcp, are available and authenticated automatically.
  • knot.methods / knot.methods.schema are agent-side only: remote/space scripts, knot run-script, and knot methods register. They are not available in MCP tool execution, event sink scripts or plugin handlers.
  • knot.event is 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, where emit() is not available.
  • knot.healthcheck runs 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.secret Pro 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 else get() raises an error.
  • knot.files.sync runs only inside a space — startup and shutdown scripts, knot space run-script and knot run-script — starting and stopping sync projects in the space’s agent. Everywhere else its functions raise an error.
  • knot.identity and knot.plugin are server-side only: MCP tool execution, event sink scripts and plugin handlers. knot.identity is also available in AI scripts.
  • AI scripts (the run_script tool) get a sandbox with no network, filesystem or AI access. Their knot.apiclient is a guarded transport that only allows /api/ endpoints, and they may import knot.identity plus the API libraries knot.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 as variables) and knot.volume. Not available there: knot.ai, knot.mcp, knot.event, knot.secret, knot.token, knot.mcp_server, knot.methods, knot.healthcheck, knot.plugin and knot.files.sync. Functions that call /space-io/ endpoints (space port forwards and tunnels, knot.jobs.run, the port forwards knot.stack.create applies) are refused; knot.stack.create for a definition with port forwards creates the spaces and then fails. knot.script can 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.apiclient transport. The API libraries, knot.mcp and knot.event.emit() fall back to the Python knot.apiclient, which configures itself from the agent’s /connect endpoint when the space’s environment sets KNOT_API_PORT (acting as the space owner), or from KNOT_URL/KNOT_TOKEN; with neither, their calls raise. knot.ai’s Client() 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.