Tunnel interface

The tunnel interface enables workshops to share network services with the host system, and vice versa. It supports connections over TCP, UDP, and Unix domain sockets.

SDKs advertise their services using tunnel interface slots. For example, if an SDK installs and advertises a web app, users can access the app from their usual browser after creating a tunnel from the host system to the workshop.

SDKs request access to services using tunnel interface plugs. Some services have dedicated interfaces (e.g., the SSH interface), which should be used instead.

Tunnel interface plug

Most SDKs declare tunnel interface plugs in their SDK definitions, but the system SDK has none by default, so system SDK plugs must be declared in the workshop definition.

A basic structure would include the name of the plug, the interface (tunnel), and, optionally, an address (endpoint).

Plugs designate addresses that clients can connect to. Regular SDKs are used for clients inside the workshop. The system SDK is used for clients from the host system.

Tunnel interface slot

Most SDKs declare tunnel interface slots in their SDK definitions, but the system SDK has none by default, so system SDK slots must be declared in the workshop definition.

A basic structure would include the name of the slot, the interface (tunnel), and, optionally, an address (endpoint).

Slots designate an address that a service can listen on. Regular SDKs should make this service available inside the workshop. The system SDK relies on the user to run this service on the host.

Connection

The interface is connected automatically at launch or refresh, provided that:

  • The plug is declared in the system SDK

  • The slot is declared in a regular SDK

  • The plug listens on localhost or a Unix domain socket

  • The plug can be matched to the slot by its name, or via a connections entry in the definition, both subject to Workshop’s validation rules.

Otherwise, it isn’t connected automatically, for security reasons. The workshop connect and workshop disconnect commands can be invoked after the workshop has started:

$ workshop connect ws/client-sdk:shared
$ workshop disconnect ws/client-sdk:shared
$ workshop connect ws/system:app ws/service-sdk:app
$ workshop disconnect ws/service-sdk:app

Establishing a tunnel connection means that Workshop will listen on the plug address, forwarding incoming network connections to the slot address.

When a system SDK plug is connected to a regular SDK slot, clients on the host can access services inside the workshop:

        flowchart LR
  subgraph Host
    Client --> Plug

    subgraph system[System SDK]
      Plug
    end
  end

  Plug -- Tunnel --> Slot

  subgraph Workshop
    subgraph regular[Regular SDK]
      Slot --> Service
    end
  end

Exposing SDK services to the host system

When a regular SDK plug is connected to a system SDK slot, clients in the workshop can access services on the host:

        flowchart RL
  subgraph Workshop
    subgraph regular[Regular SDK]
      Client --> Plug
    end
  end

  Plug -- Tunnel --> Slot

  subgraph Host
    subgraph system[System SDK]
      Slot
    end

    Slot --> Service
  end

Sharing system services with a workshop

Workshop doesn’t support connections within the system SDK or between regular SDKs. In these cases clients can connect to services directly, without the need for a tunnel.

To check if a plug or slot is connected:

$ workshop connections --all

  INTERFACE  PLUG                  SLOT                NOTES
  ...
  tunnel     ws/client-sdk:shared  ws/system:shared    manual
  tunnel     ws/system:app         ws/service-sdk:app  manual

This means that client-sdk can access the shared service running on the host, and the host can access the app service provided by service-sdk.

$ workshop info dev

  name:     dev
  base:     ubuntu@22.04
  project:  /home/user/workshop/dev
  status:   ready
  notes:    -
  sdks:
    system:
      tunnels:
        app:
          from:  0.0.0.0:8081/tcp
          to:    127.0.0.1:8080/tcp
    client-sdk:
      tracking:   latest/stable
      installed:  2024-03-02  (1)
      tunnels:
        shared:
          from:  [::1]:1080/tcp
          to:    127.0.0.1:18080/tcp
    service-sdk:
      tracking:   latest/edge
      installed:  2025-06-07  (2)

See also

Explanation:

Reference: