How to add mounts to a workshop

Workshop exposes filesystem locations to a workshop through the mount interface. A plug declared on an SDK names a target directory inside the workshop; Workshop binds a source directory to it at run-time, either from a path Workshop allocates on the host or from one inside the workshop. There are five common scenarios worth discussing.

Persist workshop-internal files on the host

To persist data that the workshop produces or uses outside the project directory (tooling caches, user data, logs) without picking and maintaining a host directory yourself, add a plug under an SDK in workshop.yaml with workshop-target only:

workshop.yaml
name: dev
base: ubuntu@24.04
sdks:
  - name: uv
    plugs:
      data:
        interface: mount
        workshop-target: /home/workshop/data

Refresh the workshop to bind the target:

$ workshop refresh

Workshop allocates a host directory for the plug at ~/.local/share/workshop/id/<PROJECT-ID>/<WORKSHOP>/mount/<SDK>/<PLUG>/ and binds it to /home/workshop/data/ inside the workshop. Files written there from the workshop survive workshop start, workshop stop, and workshop refresh because the data lives on the host.

This is the cheapest way to get persistence when the workshop, not the user, owns the lifecycle of the files.

Remount a host directory inside the workshop

If the workshop needs to consume some ad-hoc data from the host, declare the plug as before and then point it at a host path with workshop remount.

workshop.yaml
name: dev
base: ubuntu@24.04
sdks:
  - name: uv
    plugs:
      shared:
        interface: mount
        workshop-target: /home/workshop/shared

Refresh the workshop, stop it, point the plug at the host path, then start it again:

$ workshop refresh
$ workshop stop dev
$ workshop remount dev/uv:shared ~/datasets
$ workshop start dev

The host path can be absolute or relative. Workshop only swaps a live mount atomically when the new source is non-existent or empty. For a populated source like ~/datasets/, the workshop must be stopped first to avoid corrupting in-flight reads or writes, hence the workshop stop and workshop start above.

Inside the workshop, ~/datasets/ from the host is now visible at /home/workshop/shared/.

The workshop remount command sets up a durable share; use it for the host data the user owns and wants the workshop to access across many sessions, not just one.

Once a share source is set, workshop info surfaces it alongside the workshop-target:

$ workshop remount dev/uv:shared ~/datasets
$ workshop info dev

  ...
  sdks:
    uv:
      mounts:
        shared:
          host-source:      /home/user/datasets
          workshop-target:  /home/workshop/shared
  ...

The override survives workshop refresh, so the share stays in place across SDK and base updates without re-running workshop remount.

More, workshop remove does not delete the remounted host directory; the data on disk is assumed to be the user’s, so Workshop leaves it alone. What does go away with the removed workshop is its record of the remount: a fresh workshop launch starts with the auto-allocated source until you remount again.

To drop the override on demand without removing the workshop, see Reset a remount.

Expose a host directory read-only

For shared reference data, configuration, or secrets that the workshop should read but not modify, add read-only: true to the plug:

workshop.yaml
name: dev
base: ubuntu@24.04
sdks:
  - name: uv
    plugs:
      readonly:
        interface: mount
        workshop-target: /home/workshop/readonly
        read-only: true

Refresh the workshop, then point the plug at the host directory. Stop the workshop first if ~/refdata/ already holds the reference data, as in the previous scenario:

$ workshop refresh
$ workshop stop dev
$ workshop remount dev/uv:readonly ~/refdata
$ workshop start dev

Writes to /home/workshop/readonly/ from inside the workshop fail even with sudo.

The mode, uid, and gid plug attributes control the permissions and ownership of any directory that Workshop creates on behalf of the plug. Defaults are 1000:1000 for targets under /home/workshop/, /project/, or /run/user/1000/, and root otherwise.

As with any remounted plug, workshop remove leaves the host directory in place.

Share a directory between SDKs

The mount interface also can connect SDKs in the same workshop without going through the host. The slot SDK declares workshop-source to publish a directory inside the workshop; the plug SDK consumes it at its workshop-target.

For instance, the uv and jupyter SDKs ship this pattern out of the box: uv exposes /home/workshop/uv-venv/ through a venv slot, and jupyter consumes it with a venv plug at $SDK/venv/.

List both SDKs and wire them with an explicit connections entry:

workshop.yaml
name: dev
base: ubuntu@24.04
sdks:
  - name: uv
  - name: jupyter
connections:
  - plug: jupyter:venv
    slot: uv:venv

$ workshop refresh

After the refresh, jupyter and uv share the same Python virtual environment, and neither SDK is aware of the other.

Reset a remount

To drop a custom source set with workshop remount and return the plug to its auto-allocated host directory, disconnect the plug with --forget, which discards the source override, then connect the plug to the system mount slot to re-establish it:

$ workshop disconnect dev/uv:shared --forget
$ workshop connect dev/uv:shared :mount

Workshop then re-binds /home/workshop/shared/ to the auto-allocated directory under ~/.local/share/workshop/.

Note that workshop connections now lists the plug as manual in the NOTES column. That state is sticky: it survives workshop refresh and workshop stop plus workshop start cycles, so the share stays in place across normal lifecycle operations.

To revert connections and mounts wholesale, use workshop restore. For a single plug, run workshop disconnect with --forget to disconnect it and forget its manual state.

See also

Explanation:

Reference: