knot.tunnel
The knot.tunnel library lists and closes the current user’s tunnels — every tunnel open under your name, whichever client or space runs it — and reads the tunnel server settings. Tunnels a space runs are started and stopped with knot.space.tunnel_start and tunnel_stop. Every function needs the Use Tunnels permission.
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 |
|---|---|
list() |
List your open tunnels |
server_info() |
Get the tunnel server settings |
delete(name) |
Close one of your tunnels |
list()
List your open tunnels from every client and space.
Returns: list of dicts sorted by name, each containing:
name(string): Full tunnel name,<username>--<tunnel>address(string): Public URL, e.g.https://alice--web.tunnel.example.com
server_info()
Returns: dict containing:
domain(string): Tunnel domain suffix, e.g..tunnel.example.comtunnel_servers(list): Tunnel server URLs
delete(name)
Close one of your tunnels, disconnecting the client that runs it.
Parameters:
name(string): The full<username>--<tunnel>name, or the bare tunnel name
Returns: bool - True on success. Raises if the tunnel is not found.
Examples
import knot.tunnel as tunnel
for t in tunnel.list():
print(t["name"], t["address"])
tunnel.delete("web")