knot.server
The knot.server library exposes server-wide information: the server’s settings, the cluster’s nodes, the loaded plugins, and a search across everything the current user may see.
Execution Environment
| Environment | Behaviour |
|---|---|
Embedded (MCP tool execution, event sinks, plugin handlers, remote/space scripts, knot run-script) |
Available; authenticated automatically via the Go-provided knot.apiclient transport. |
| Health check scripts | Only when the space’s environment sets KNOT_API_PORT or KNOT_URL/KNOT_TOKEN: there is no built-in transport, so the Python knot.apiclient configures itself from the agent (as the space owner) or those variables, and calls raise otherwise. See Environment Compatibility. |
| External (standalone scripts) | Python implementation; configure knot.apiclient first (or set the KNOT_* environment variables). |
Functions
| Function | Description |
|---|---|
info() |
Get server-wide information |
host_label(user, name, port) |
The first label of a space’s web port host |
ping() |
Check the server is reachable and the credentials work |
cluster_info() |
List the cluster’s server nodes |
search(query) |
Search everything you may see by name |
plugins() |
List the loaded server plugins and what each provides |
Usage
import knot.server as server
info = server.info()
print(info['wildcard_domain'])Info Properties
info() returns:
version- The knot server version string.wildcard_domain- The server’s wildcard domain for space web-port URLs (e.g.*.knot.example.com); empty when none is configured.tunnel_domain- The server’s tunnel domain as a dot-prefixed suffix (e.g..tunnel.example.com) that appends straight after a tunnel name; empty when none is configured.
host_label(user, name, port)
The first label of the host a space’s web port is reached at, before the wildcard domain: <user>--<name>--<port>, lowercased. DNS allows at most 63 characters there, so when the label would be longer, the name is cut short and ends with a hyphen and an 8-character hash of the full name, which knot routes by. The web interface and events build the same host.
Parameters:
user(string): The username of the space’s ownername(string): The space’s name, one of its alt names, or a pool’s nameport(int or string): The port number, or"vnc"for web VNC
Returns: string - The label, such as alice--web-app--8080
import knot.server as server
domain = server.info()["wildcard_domain"].lstrip("*")
url = "https://" + server.host_label("alice", "web-app", 8080) + domainping()
Check the server is reachable and the credentials work.
Returns: dict containing status (True), version (the server’s knot version) and zone (the zone of the server that answered).
cluster_info()
List the servers of the cluster, as the Cluster Info page shows them. Needs the View Cluster Info permission.
Returns: list of dicts sorted by address, each containing:
id(string): Node IDaddress(string): Advertised cluster addressstate(string): Gossip state, e.g.alive,suspect,deadzone(string),hostname(string)allocated_spaces(int): Spaces assigned to the noderunning_spaces(int): Those of them deployedruntimes(list): Container runtimes the node offers, e.g.["docker"]— known only for the node that answeredmetadata(dict): All the node’s gossip metadata, as strings
search(query)
Search everything the current user may see by name, as the web UI’s command palette does. Matching is a case-insensitive substring match on each entity’s name, with at most 5 hits per type. Admin entities appear only with the matching manage permission; personal ones (scripts, skills, commands, MCP servers, tokens) are your own plus global ones.
Parameters:
query(string): Text to look for
Returns: dict containing query and one list per type — pages, spaces, templates, variables, volumes, stacks, scripts, skills, commands, mcp_servers, event_sinks, users, groups, roles and tokens — of dicts with id, name and, where there is one, description. A type with no hits has an empty list.
import knot.server as server
hits = server.search("web")
for s in hits["spaces"]:
print(s["id"], s["name"])plugins()
List the loaded server plugins and what each provides. Needs the Manage Roles permission. The endpoint exists only while plugins are loaded, so with none the call raises.
Returns: dict containing:
count(int): Number of loaded pluginsplugins(list): Dicts withname,version,description,permissions({id, label}),menus,pages,peers,mcp_tools({name, description, handler, permission, parameters}),handlers({handler, permission}),field_handlers({id, label, permission}) andlibs({name, version})failed(list): Plugins that did not load, each{name, path, reason}warnings(list): Load warnings