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)

• Custom device interface (manually connected)

• Desktop interface (manually connected)

• GPU interface (auto-connected)

• Mount interface (auto-connected)

• SSH interface (manually connected)

• Tunnel interface (conditionally auto-connected)

Plugs and slots

Interfaces become useful when SDKs declare plugs to consume them and slots to provide them. See Plugs and slots for the full mechanics, including the wiring you can express in the workshop definition.

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, custom device, desktop, and SSH interfaces require manual connection.

Auto-connection also depends on where a plug or slot lives. Additional slots defined for the system SDK, for interfaces such as tunnel or mount, are not auto-connected at launch or refresh, largely for security reasons: the system SDK exposes sensitive host system resources. To the contrary, plugs added under the system SDK can be auto-connected, because they expose workshop internals.

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

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