Host share mounts¶
A workspace can mount host directory trees into its guest. The daemon's config
gives the allowed roots a guest's mounts must sit under via
mount_host_roots, and -- on a VM-hosted daemon -- the trees its own VM
carries. On the guest side, each workspace gives a host path, the absolute
guest path it lands at, and a mode (ro or rw, defaulting to rw).
You can motify mount_host_roots Within the daemon hosts's
~/.config/msksd/msksd.yaml:
# the operator allows the roots (msksd.yaml; reloadable on SIGHUP)
mount_host_roots:
- /srv/projects
- /srv/refs
With this configuration active in the msksd daemon, you can successfully mount
files from the host's /srv/projects and /srv/ref locations:
# a workspace mounts host paths (applies at its next start)
msks create ws1 --share /srv/projects:/mnt/projects
msks mount ws1 /srv/refs:/mnt/refs:ro
msks umount ws1 /srv/refs
What a mount is¶
A workspace's mount gives a host path, an absolute guest path, and a mode. The
guest path becomes a root-owned mount point inside the VM. The location must
be absolute, below the filesystem root, outside the pseudo-filesystems
(/proc, /sys, /dev, /run) and outside /home.
Two mounts of one workspace never overlap, and a host path appears once per workspace. Mounts follow next-start semantics, like resize: setting them never touches a running VM, and the next start attaches the current set. A restart after a change lands the new set and prunes the dropped one.
The mount gates¶
Each host path checks two gates at set time:
- The policy gate (every host): the path, resolved against
symlink escapes, must sit under one of the allowed roots
under
mount_host_roots. A path outside them is refused with the instruction to add it or a parent to the daemon's config. A symlink that resolves outside its allowed root is refused the same way. - The mount gate (VM-hosted daemons,
mount_host_mode: prefix): the path, translated under/mnt/msks, must sit under a root the daemon's VM actually has mounted. A path whose root is not mounted is refused with the instruction to recreate the VM from a template that mounts it. vz mounts are fixed at VM start, so a config edit cannot add one. This knob is typically only used on MacOS, to account for double-mounting under the Lima VM filesystem.
The spec grammar splits its fields on colons, so a host path
containing one is inexpressible on the wire. --share and the
TUI editor both refuse it, giving the field that the colon broke.
A mount attaches read-write unless it says ro: the trust
decision is made before the mode matters (the root is allowed),
and a mount that wants less says ro. Read-write mounts hold no
exclusivity: any number of workspaces may attach the same tree.
The skip behavior¶
A start proceeds when a mount cannot attach caused by a root the reload removed
from the allowed list, a path whose root the daemon's VM no longer mounts, a
symlink that moved out from under its allowed root, or a path that vanished
since the set. Each publishes an event (mount.skipped) giving the mount and
the reason, and the row carries the standing marker (msks ls prints running,
1 mount skipped) until the config and the row agree again. The workspace's
other mounts attach.
Coherence between guests¶
A host tree attaches read-write to any number of workspaces at once, and every
attach forces virtiofs cache=never. This means data writes become coherent
through the host page cache, and lockfile coordination (O_EXCL creates: git,
cargo) works because the host kernel serializes it. Things that do not
coordinate between guests on the same share: flock/fcntl locks (each attach
is its own virtiofsd), and mmap coherence.
Shares on a macOS host¶
On a Mac the daemon runs inside its own Linux VM (Lima over Apple's Virtualization.framework, on an M3-or-newer Mac), and a shared Mac folder crosses two hops to reach a workspace: vz virtiofs carries it from macOS into the daemon's VM under the reserved prefix and one virtiofsd per attached share carries it from there into the workspace guest.
The client speaks Mac paths throughout (--share ~/code:/mnt/code), and the
daemon's prefix host mode does the translation before the two
gates run. The Lima template mounts the invoking user's home
under the prefix at VM creation, writable, so the common case needs no edit. A
share root outside it (another user's home, a /Volumes tree) is a template
edit plus VM recreation, and the mount gate's refusal suggests a remedy.
The far end of the share is the Mac's own volume, and its behaviors cross with the tree. Four of them are contract, not configuration:
macOS: Watchers poll¶
File events do not cross virtiofs. Changes made on the Mac (an editor's save, a build's output) reach every attached workspace as data, promptly coherent the way coherence between guests describes, but no inotify event follows them: the share carries data, not notifications.
Watchers on shared trees run in polling mode (Vite's server.watch.usePolling
setting, jest's --watchAll, or the tool's own poll option), and a tool that
can watch only through events cannot watch a share at all. Signaling built on
the same polling takes one care: a file's existence becomes visible before its
content does (a writer creates empty, then fills). A poller therefore waits for
a completion marker the writer emits after the data, never for the file itself.
macOS: Case and normalization follow the Mac volume¶
The tree a workspace mounts is a Mac volume, and its naming rules cross with it. A Mac's default volume matches names case-insensitively, storing them as typed (case-preserving), and compares them Unicode-normalization-insensitively: a name typed composed (NFC) and the same name decomposed (NFD) are one file.
Tools inside the workspace that expect Linux naming can fail on the share. Two
names differing only in case cannot coexist in one directory (a checkout
holding both README and readme collapses them), and a tool comparing
filename bytes sees NFD where the Mac accepted NFC.
Archive and package tooling that hashes or compares names byte-for-byte can report a mismatch against a Linux-built expectation. A tree that must keep Linux naming rules exactly must live in the workspace's own storage, not on a mount.
macOS: The rw single-writer contract¶
An rw share allows the workspace as a writer. Locks taken inside the
workspace hold there and stop there: flock and fcntl locks end at the
workspace's own virtiofsd, and the Mac side honors none of them.
Finder, an open editor, or a Mac-side build writes past any lock the workspace
took. Between workspaces, coherence between
guests governs: lockfile creates (O_EXCL: git,
cargo) serialize through the host kernel and work cross-workspace;
flock/fcntl do not cross an attach.
Trees whose tools lock and treat the lock as the whole story (a cargo or bazel cache, a SQLite database, anything with a journal on disk) take one writer at a time: the workspace's, or the Mac's. A Mac that only reads the share (browsing in Finder, opening a file) travels the coherence contract. A Mac-side writer into a lock-using tree races the workspace.
macOS: External volumes stay busy while shared¶
A file the stack holds open keeps its Mac volume mounted. A disk whose tree is shared into a running workspace therefore refuses to eject (the Finder reports the volume in use) until the workspace stops and its files close.
To allow the volume to unmount, msks stop on the workspace and eject the
disk.
The plumbing¶
Each attached share is one virtiofsd process using the platform's own
virtiofsd package, spawned before the VM and stopped with it.
The default virtiofsd binary name resolves on PATH first and then the
package's install locations off PATH, so the daemon finds it without
configuration. MSKSD_VIRTIOFSD gives a different binary.
The mounts need virtiofsd 1.13.0 or newer: the identity translation and the read-only enforcement both landed upstream there, and an older binary refuses the daemon's arguments at start.
File ownership translates in both directions. Writes from the guest land on the host as the daemon's own user, whatever guest account made them. Host-side ownership stays advisory, as with a typical bind mount.
Files read back inside the guest present as the workspace's own user: the login
user the workspace gives, or the image's built-in msks account when it gives
none. The share's tree therefore reads as the logged-in user's files, and a
file the guest creates stays writable by the account that created it.
Extended attributes remap under one host prefix (user.virtiofs.), so a guest
cannot write host security labels or root-owned namespaces through the
share.