Interface concepts

Interfaces are a mechanism for communication and resource sharing. It is an integral part of workshop confinement, ensuring that each workshop operates in its own isolated environment, while still allowing controlled interactions among the SDKs and with the host.

In Workshop, SDKs can act as providers and consumers of resources such as the GPU, or file directories. Host system resources are exposed via the system SDK that is present in every workshop by design.

For a workshop to be operational, the SDKs listed in its definition must connect to the resources they expect. Such connections are uniformly established via the interface system.

To achieve this, Workshop implements a counterpart to snapd’s interface manager, which controls whether an SDK can use resources beyond its confines. You can think of specific interfaces as resource types: filesystem, hardware, computing, and so on.

Specific interfaces are predefined and implemented by Workshop, so you cannot create a custom interface type. Currently, Workshop and SDKcraft support the following:

• Camera interface (manually connected)

• Desktop interface (manually connected)

• GPU interface (auto-connected)

• Mount interface (auto-connected)

• SSH interface (manually connected)

Plugs and slots

To make use of these interfaces, SDKs and workshops define slots. For example, a mount interface slot creates a source directory to be mounted inside the workshop via a plug.

Further, SDKs and workshops define plugs to connect to a slot of a certain interface type. For example, a mount interface plug mounts the slot to a target directory inside the workshop.

You can think of the plug as the recipient of the resources exposed by the slot; note that a slot can handle connections with multiple plugs.

Connections can be established:

• Automatically: By running workshop launch, workshop refresh, or workshop start.

• Manually: By running workshop connect after the workshop has started, or by listing connections in the workshop definition and running workshop refresh.

All connections are subject to validation. Also, automatic connections require plugs and slots to have matching details and aren’t allowed for some interfaces, such as ssh-agent. Finally, the order of automatic connections is not guaranteed, so you should not rely on it.

Validation

All plugs and slots defined for a workshop directly or via its SDKs are checked to make sure they can be installed as part of the workshop and then connected. For this, Workshop uses a set of internal rules.

Each interface has its own rule set; for example, the mount interface plug can be installed and auto-connected based on its rules alone. However, other interfaces may have different rules, such as allowing installation but not auto-connection for ssh-agent.

Connections

From the user perspective, connections can be established through the interface system in several ways:

• The connections section of the workshop definition and the workshop connect command can be used to link interface plugs to respective slots, allowing the SDKs to orderly access the resources.

• Conversely, the workshop disconnect command terminates existing interface connections, revoking the access to the resources granted by the connection.

• Finally, the workshop connections command lists all existing connections and their states, providing an overview of how workshop connections are laid out.

Some plugs can be auto-connected to their slots at launch or refresh. This behavior varies by interface, but the overall aim is to conduct reasonably in each case: the mount and the GPU interfaces are auto-connected, whereas the camera, desktop, and SSH interfaces require manual connection.

To know how each kind of connection is treated when a workshop is launched, refreshed, or restored, see Connections across refresh and restore.

Plug bindings

SDKs usually access host resources via interface plugs. When multiple SDKs try to use the same resource in conflicting ways, the workshop won’t launch and shows an error.

To fix this issue, you can bind one plug to another of the same interface type. This makes both plugs point to the same resource without conflicts. Any action performed on one plug (like mounting or remounting) thus automatically applies to all bound plugs.

When you run workshop connections, a bound plug will have bind listed under Notes, along with the line number of the target plug:

$ workshop connections digits

  INTERFACE  PLUG                    SLOT                 NOTES
  mount      digits/torchaudio:hub   digits/system:mount  bind.1
  mount      digits/torchvision:hub  digits/system:mount  bind.1

Here, both plugs are listed as bind.1, pointing to torchaudio:hub in the first line.

Related CLI operations

A number of basic workshop operations affect plugs and slots in different ways.

When you workshop launch a workshop, an auto-connect task handles each interface plug, finding a candidate slot, verifying the plug’s eligibility for the slot based on their declarations and connecting the two.

On workshop refresh, existing connections are preserved in the refreshed workshop if their plugs were connected before the operation. A newer version of an SDK may drop a plug that was previously connected; such connections are removed, but the host-based content remains.

On workshop remove, both the interface connections and the default host directories (if any have been created, for example, to accommodate mount interface slots) are removed.

Also, you can manually enable or disable connections with workshop connect and workshop disconnect, whereas workshop connections can list all connections that have been established by any Workshop projects.

Note

We remove content stored in our default locations because it’s not a good idea to keep user data forever. Thus, at least some commands will delete this data to prevent it from piling up in hidden places where it’s unlikely to be used again.

See also

Explanation:

• SDKs

• Workshops and projects

How-to guides:

• How to fix plug conflicts with binding

Reference:

• Command-line interfaces

• workshop connect

• workshop connections

• Workshop definition

• workshop disconnect

• workshop info

• workshop launch

• workshop refresh

• workshop remove