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.com
  • tunnel_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")