Work with interfaces¶

This is the second section of the four-part series; it explains how to work with interfaces. It relies on the knowledge gained in the Get started with workshops section, where you learned how to create and run workshops. Here, you will learn how to make better use of SDKs in your workshop and integrate them with the host system.

SDKs use interfaces to interact in an organized manner, exposing the resources they provide via slots and consuming them via plugs; the layout of these plugs and slots is defined by the SDK publishers.

For uniformity, security, and control, various host system capabilities (camera, GPU, and so on) are also exposed to the workshop via the same interface mechanism with a designated system SDK.

Manage connections¶

To check out the connected interfaces of a workshop, list the connections:

$ workshop connections

  INTERFACE  PLUG               SLOT              NOTES
  gpu        dev/ollama:gpu     dev/system:gpu    -
  mount      dev/ollama:models  dev/system:mount  -

This lists two interface plugs, both provided by the ollama SDK under the dev workshop.

The first one is a GPU interface plug named dev/ollama:gpu. It enables the workshop to use the host system’s GPU by connecting to the dev/system:gpu slot.

Also, there’s a mount interface plug named dev/ollama:models. As seen in the workshop info output, it was automatically connected at launch to the dev/system:mount slot, indicated by the ellipsis in the host-source path.

Note that some interfaces are auto-connected, while some are not; this depends on their built-in security policy defined by Workshop. For instance, you can’t use the ssh-agent interface without connecting it manually.

In any case, you can connect and disconnect interfaces at will. To check the connection state, run workshop connections:

$ workshop disconnect dev/ollama:models
$ workshop connections

  INTERFACE  PLUG            SLOT            NOTES
  gpu        dev/ollama:gpu  dev/system:gpu  -

$ workshop connect dev/ollama:models :mount
$ workshop connections

  INTERFACE  PLUG               SLOT              NOTES
  gpu        dev/ollama:gpu     dev/system:gpu    -
  mount      dev/ollama:models  dev/system:mount  manual

You can remount a mount interface plug to a new location on the host. For example, to preserve models, conventionally stored under ~/.ollama/models/, after the workshop is removed or use some models downloaded previously, you can remount to a directory in your home:

$ mkdir -p ~/.ollama/models
$ workshop remount dev/ollama:models ~/.ollama/models
$ workshop info

  name:     dev
  base:     ubuntu@24.04
  project:  /home/user/ollama-python-project
  status:   ready
  notes:    -
  sdks:
    system:
      installed:  (1)
    ollama:
      tracking:   vulkan/stable
      installed:  0.9.6  2025-11-19  (214)
      mounts:
        models:
          host-source:      /home/user/.ollama/models
          workshop-target:  /home/workshop/.ollama/models

This makes /home/user/.ollama/models/ on the host act as the models storage for the workshop.

Add plugs, slots¶

You can modify the behavior of the SDKs you installed in your workshop, tailoring it to your needs and connecting them to other SDKs or the host system.

To do this, you add plugs and slots to the SDKs in the workshop definition, allowing you to customize the initial plug and slot layout to your requirements.

This scenario usually arises when you want to connect different SDKs running in the workshop or expose some service from the workshop to the host system.

Let’s look at an example. Add the jupyter SDK to the workshop to run Jupyter notebooks with the Ollama models:

workshop.yaml¶

name: dev
base: ubuntu@24.04
sdks:
  - name: ollama
    channel: vulkan/stable
  - name: jupyter

$ workshop refresh

  "dev" refreshed

Next, add the tunnel interface plug under the system SDK in the workshop definition; this exposes the Jupyter server, now available in the workshop, to the host system at a port of your choice (here, 8989):

workshop.yaml¶

name: dev
base: ubuntu@24.04
sdks:
  - name: ollama
    channel: vulkan/stable
  - name: jupyter
  - name: system
    plugs:
      jupyter:
        interface: tunnel
        endpoint: 127.0.0.1:8989

The slot we’re going to connect this plug to comes from the SDK itself and is named jupyter, so you don’t have to add it manually:

$ workshop connections --all

  INTERFACE  PLUG                SLOT                      NOTES
  gpu        dev/ollama:gpu      dev/system:gpu            -
  mount      dev/jupyter:venv    dev/system:mount          -
  mount      dev/ollama:models   dev/system:mount          -
  tunnel     -                   dev/ollama:ollama-server  -
  tunnel     dev/system:jupyter  dev/jupyter:jupyter       -

Refresh the workshop to enable the tunnel; Workshop will auto-connect the plug to the slot by matching their names (the plug’s name is also jupyter). Check the result using workshop info:

$ workshop refresh

  "dev" refreshed

$ workshop info

  ...
  sdks:
    system:
      installed:  (1)
      tunnels:
        jupyter:
          from:  127.0.0.1:8989/tcp
          to:    127.0.0.1:8888/tcp
  ...

Now, JupyterLab is available at the plug address:

$ curl -w '\n' http://127.0.0.1:8989/api

  {"version": "2.17.0"}

Note

For additional details of using the tunnel interface, see this guide: How to forward ports with tunneling.

Wire jupyter to a uv-managed Python environment¶

So far, jupyter:venv auto-connects to the system:mount slot, which gives Jupyter a private host directory for its virtual environment. A more interesting wiring uses the uv SDK, the standard Python tooling SDK in Workshop; uv exposes a venv slot that other Python-based SDKs can plug into, so Jupyter and uv share a single environment.

Edit the workshop definition to add uv before jupyter in the sdks: list, so that uv’s setup-project hook prepares the shared virtual environment before any consuming SDK installs into it. Then declare the connection in a top-level connections: block:

workshop.yaml¶

name: dev
base: ubuntu@24.04
sdks:
  - name: ollama
    channel: vulkan/stable
  - name: uv
  - name: jupyter
  - name: system
    plugs:
      jupyter:
        interface: tunnel
        endpoint: 127.0.0.1:8989
connections:
  - plug: jupyter:venv
    slot: uv:venv

Apply the new definition by refreshing the workshop:

$ workshop refresh

dev/jupyter:venv now connects to dev/uv:venv instead of falling back to dev/system:mount:

$ workshop connections --all

  INTERFACE  PLUG                SLOT                      NOTES
  gpu        dev/ollama:gpu      dev/system:gpu            -
  mount      dev/jupyter:venv    dev/uv:venv               -
  mount      dev/ollama:models   dev/system:mount          -
  mount      dev/uv:cache        dev/system:mount          -
  tunnel     -                   dev/ollama:ollama-server  -
  tunnel     dev/system:jupyter  dev/jupyter:jupyter       -

This is your first taste of slot/plug coordination between two nonsystem SDKs; for the full Python workflow with uv, see How to manage Python environments with the uv SDK.

Next steps¶

This was the last step in this tutorial section; you’re halfway through! Now you are familiar with the essentials of interfaces in Workshop.

Your next step is to learn even more about workshop customization, creating experimental SDKs quickly with the workshop sketch-sdk command; proceed to the Customize with sketch SDKs section.