Shared Folder

Shared folders allow directories from the host Mac to be mounted directly inside a macOS virtual machine. This makes it easy to share source code, scripts, and build artifacts between the host and VM

What are shared folders?

A shared folder maps a directory on the host system into a running virtual machine.

When enabled:

• Files appear instantly inside the VM

• Changes are reflected in real time

• No network file shares are required

• No duplication of data occurs

Shared folders are provided natively by Apple’s Virtualization.framework.

---

Common use cases

Shared folders are commonly used for:

• Sharing source code into a VM

• Running build scripts from the host

• Accessing CI artifacts

• Testing tools against local repositories

• Avoiding large file duplication

They are especially useful for development and automation workflows.

---

How shared folders work

CiderStack uses macOS’s built-in directory sharing support.

Behind the scenes:

• The host directory is mounted read-write into the VM

• The VM accesses the folder as a normal filesystem path

• File changes propagate immediately

No SMB, NFS, or network configuration is required.

---

Adding a shared folder

Shared folders can be added using either the GUI or the CLI.

---

Using the GUI

1. Select a virtual machine

2. Open Settings → Shared Folders

3. Click Add Folder

4. Choose a directory from the host

5. Assign a share name

6. Save changes

The folder will be mounted the next time the VM starts.

---

Using the CLI

cider vm share add myvm ~/code --name code

This command:

• Adds the host directory ~/code

• Assigns the share name code

• Persists the configuration to the VM

---

Listing shared folders

To view configured shared folders:

cider vm share list myvm

This shows:

• Host path

• Share name

• Enabled or disabled state

---

Removing a shared folder

To remove a shared folder:

cider vm share remove myvm code

The mapping is deleted and will no longer be mounted.

---

Enabling and disabling sharing

Shared folders can be toggled without deleting their configuration.

Disable sharing

cider vm share disable myvm

Enable sharing

cider vm share enable myvm

This is useful when:

• Testing isolation behavior

• Debugging build scripts

• Temporarily preventing file access

---

Where shared folders appear in the VM

Inside the virtual machine, shared folders are mounted automatically at:

/Volumes

Each share appears using its assigned name.

Example:

/Volumes/code

---

Permissions

Shared folders inherit permissions from the host filesystem.

• File ownership is handled by macOS

• Read/write access depends on host permissions

• No additional VM configuration is required

If access issues occur, verify host directory permissions first.

---

Performance characteristics

Shared folders are optimized for developer workflows.

• Changes appear immediately

• No background sync process

• No polling or indexing required

Performance is suitable for:

• Source code editing

• Build systems

• Script execution

For extremely heavy I/O workloads, placing files directly inside the VM disk may perform better.

---

Limitations

Shared folders have a few important constraints:

• Available only while the VM is running

• Must be configured before VM startup

• Not intended as long-term storage

• Not a replacement for network file systems

They are designed for convenience and workflow efficiency.

---

Best practices

To get the most from shared folders:

• Share source code, not build outputs

• Keep shared paths shallow

• Avoid sharing entire home directories

• Use snapshots before major changes

• Disable sharing when testing isolation

---

Summary

Feature	Description
Purpose	Share host directories with VMs
Mount point	/Volumes/<share-name>
Live sync	Yes
Network required	No
CLI support	Yes
Enable/disable	Supported
Backed by	Apple Virtualization.framework

---

Related commands

cider vm share add <vm> <path> --name <name>
cider vm share list <vm>
cider vm share remove <vm> <name>
cider vm share enable <vm>
cider vm share disable <vm>

---

What’s next

You may want to explore:

• Networking

• Images & OCI Registries

• Snapshots & Instant Clones

• Fleet Manager Overview

• CI/CD workflows