Skip to content

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:

  1. 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.
  2. 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.