How to configure a mount

This guide shows how to tune ownership and permissions on a mount interface plug, overriding the defaults that Workshop derives from the target path.

By default, Workshop applies the following rules when a mount plug omits ownership and permission attributes. The attributes take effect when Workshop creates the target path and any missing parent directories; a path that already exists keeps its ownership and permissions.

  • uid and gid default to 1000 when workshop-target is at or below /home/workshop, /project, or /run/user/1000. Otherwise, both default to 0 (root).

  • mode defaults to 0o755 when the uid, set explicitly or resolved by the previous rule, is 0 (root), and to 0o775 otherwise.

  • read-only defaults to false.

Override the defaults when a mount lives outside the user-owned paths, when a mount stores secrets that should not be world-readable, or when the SDK should not be able to write to the mount.

Prerequisites

You need an sdkcraft.yaml that declares at least one mount plug; SDK plugs and slots covers the declarations. The attributes below extend the plug entries under the top-level plugs: key.

Set explicit ownership outside the user-owned paths

For a mount whose target lives outside /home/workshop, /project, or /run/user/1000, the ownership defaults to root. If the workshop user needs to read or write the mount, set uid and gid to 1000:

sdkcraft.yaml
plugs:
  state:
    interface: mount
    workshop-target: /var/lib/example
    uid: 1000
    gid: 1000

An explicit uid doesn’t change the default for gid, which still follows the target path, so set both attributes. The default mode, in contrast, follows the resolved owner and becomes 0o775 here.

Tighten permissions for a private mount

For a mount that stores credentials, tokens, or other secrets, tighten mode to 0o700 so that only the owning user can access it:

sdkcraft.yaml
plugs:
  secrets:
    interface: mount
    workshop-target: /home/workshop/.private-secrets
    mode: 0o700

The owner keeps the path-based default (here, the workshop user, since the target is under /home/workshop).

Mark a mount read-only

For a mount that should expose data without allowing the consumer to modify it, set read-only to true:

sdkcraft.yaml
plugs:
  toolchain:
    interface: mount
    workshop-target: /home/workshop/.local/share/example-toolchain
    read-only: true

This is appropriate for shared resources that the SDK consumes but never writes to.

Verify inside a workshop

After adding the SDK to a workshop definition and launching the workshop, inspect the mounts to confirm the applied ownership and permissions. The numeric uid and gid show how Workshop resolved the attributes:

$ workshop exec dev -- ls -ldn /home/workshop/.private-secrets

  drwx------ 2 1000 1000 4096 May 14 10:32 /home/workshop/.private-secrets

For a read-only mount, attempting to write returns an EROFS error:

$ workshop exec dev -- touch /home/workshop/.local/share/example-toolchain/probe

  touch: cannot touch '/home/workshop/.local/share/example-toolchain/probe': Read-only file system

See also

Explanation:

How-to guides:

Reference:

Tutorial: