# Share a host folder
Access Mac files from a FreeBSD guest using VirtIO-9P, including when guest networking is disabled.

## Start with a read-only export
Stop an existing VM cleanly before adding a share: shares are attached at boot. For an already configured VM, use a tag and a local directory that exists:

```sh
cubectl start freebsd-dev --share work "$HOME/Dev/project"
```

Replace the example path with your project directory. Read-only is the default. Supplying any share flags replaces the entire configured share list for that launch, rather than appending to it.

## Mount inside FreeBSD
The documented tested guest is FreeBSD 14.4 ARM64. Run these commands as root inside the guest:

```sh
kldload virtio_p9fs
mkdir -p /mnt/host
mount -t p9fs work /mnt/host
ls /mnt/host
```

The tag work must match the launch flag. If the module is already loaded, continue to the mount step. The host enforces a read-only export even if the guest does not request a read-only mount.

## Allow guest edits
When you intentionally want the guest to modify the original host files, launch with --share-rw instead. Guest writes are real changes to the exported Mac directory.

```sh
cubectl start freebsd-dev --share-rw work "$HOME/Dev/project"
```

Use this command only when the VM is stopped; it is an alternative to the earlier start command. Unmount the share inside FreeBSD before shutdown:

```sh
umount /mnt/host
```

## Know the limits
Exports use the host launching user's permissions. Guest ownership appears as UID/GID 0:0; arbitrary per-user ownership mapping and ACL/xattr support are not provided. Guest caching can delay visibility of host edits. Unmount and remount to refresh a stale view.

Hot plugging and automatic guest mounting are not implemented. Keep databases and workloads requiring local filesystem locking semantics on virtual disks.

## Reference
See the [shared-folder runbook](https://github.com/darcyliu/cube/blob/main/docs/shared-folders.md) for persistent mount setup, permissions, caching, filesystem semantics, and validation scope.