How to use host devices

Workshop exposes arbitrary host devices to a workshop through the custom device interface, identified by the device subsystem they belong to (for example, input, tty, or usb). A plug declared on an SDK names the subsystem; Workshop then passes every host device in that subsystem into the workshop once the plug is connected.

The interface is never connected automatically, so reaching a host device follows a short sequence: find the subsystem, declare a plug, connect the interface, then use the devices inside the workshop.

Identify the device subsystem

Every device node on the host belongs to a subsystem defined by the Linux kernel. Query the subsystem of a device with udevadm info:

$ udevadm info --query=property --property=SUBSYSTEM /dev/input/event0

  SUBSYSTEM=input

The device at /dev/input/event0 belongs to the input subsystem. That name is what the plug declares in the next step.

Declare a custom device plug

A custom device plug lives on an SDK, not on the workshop directly. To add one without publishing a separate SDK, declare an in-project SDK: a small definition stored under .workshop/ that the workshop references with the project- prefix.

Give the SDK a name and declare the plug, naming the subsystem from the previous step:

.workshop/input-sdk/sdk.yaml
name: input-sdk
plugs:
  input-device:
    interface: custom-device
    subsystem: input

Then reference the in-project SDK from the workshop definition:

.workshop/dev.yaml
name: dev
base: ubuntu@24.04
sdks:
  - name: project-input-sdk

Note

The project- prefix appears only in the sdks: list. Workshop strips it internally, so the SDK keeps its bare name, input-sdk, in connections and command arguments.

Connect the interface

Launch the workshop to install the SDK:

$ workshop launch dev

The custom device interface stays disconnected after launch, for security reasons. Connect the plug to the workshop’s custom device slot by hand:

$ workshop connect dev/input-sdk:input-device :custom-device

The first argument is the plug, <WORKSHOP>/<SDK>:<PLUG>. The trailing :custom-device selects the slot that the built-in system SDK provides for every workshop.

Connecting the plug makes all existing host devices in the subsystem available inside the workshop. While the connection is live, devices attached to the host afterwards appear too, and detached devices disappear.

Verify the connection

List the connections to confirm the plug is wired to the slot. The --all flag includes disconnected plugs:

$ workshop connections --all

  INTERFACE      PLUG                        SLOT                      NOTES
  custom-device  dev/input-sdk:input-device  dev/system:custom-device  manual

The manual note marks a connection made by hand rather than one established automatically at launch.

Access the devices

Open a shell in the workshop and list the devices from the connected subsystem:

$ workshop shell dev
workshop@dev:~$ ls /dev/input/

  event0  event1  mice

The host’s input devices are now reachable inside the workshop.

To revoke access, disconnect the plug:

$ workshop disconnect dev/input-sdk:input-device

See also

Explanation:

How-to guides:

Reference: