knot knot

Tunnels

Knot tunnels allow HTTP and HTTPS services running on a local workstation or within a space to be exposed on the internet via a Knot server. The protocol (http or https) names what the local service speaks; visitors reach the tunnel through the server’s tunnel listener either way.

Configuring the Server

Tunnels require the server’s tunnel listener to be configured — see Tunnel Server Configuration for the listen_tunnel and tunnel_domain settings and their DNS requirements.

Tunnel addresses are built as <user>--<tunnel name>.<tunnel domain>, for example example--tunnel1.tunnel.knot.internal.

Prerequisites

  • The server has listen_tunnel set. Without it the Tunnels menu item isn’t shown and tunnels can’t be created.
  • The user holds the Use Tunnels permission (see Roles).
  • The user’s tunnel quota isn’t used up. Maximum Tunnels is set on the user and their groups and the values are added together; 0 everywhere means no limit.

Creating a Tunnel

Tunnels can be created either on a local machine (desktop) or within a space (managed by the knot agent).

  • Desktop tunnels (described below) run as a foreground process on your local machine and live for the life of that command.
  • Agent tunnels, started inside a space, can optionally be handed to the knot agent so they keep running after the launching command exits. See Agent Tunnels for --daemon, stop, and list.

Creating a Tunnel on a Local Machine

  1. Connect to the Knot Server Open a terminal and connect to the Knot server by running the following command (replace the URL with the actual server address):

    knot connect https://knot.internal:3000
    • The connect command only needs to be run once or if the login expires.

  2. Create a Tunnel Run the tunnel command with the protocol, port, and tunnel name:

    knot tunnel http 8080 test1
    • This creates a tunnel to the local port 8080 with the address example--test1.tunnel.knot.internal.
    • If the local service itself speaks HTTPS, use knot tunnel https 8443 test1. The local certificate isn’t verified by default, so self-signed certificates work; use --port-tls-name to set the name presented to the local service (TLS SNI), and --port-tls-skip-verify=false to require a valid certificate.
    • Stopping the knot tunnel command will stop and remove the tunnel.

Creating a Tunnel in a Space

Run the same command from a terminal inside a space:

knot tunnel http 8080 test1

By default this behaves like the desktop version — the tunnel lives for the life of the command and is created on the server that owns the space. To let the knot agent own the tunnel so it keeps running after the command exits, add --daemon, and use knot tunnel stop / knot tunnel list to manage it. See Agent Tunnels for the full agent-managed workflow.

A tunnel — foreground or --daemon — can also target a different knot server with --server / --token or a configured --alias, and several tunnels against different servers can run side by side — see Targeting Another Knot Server.