Shared Directories

Share host directories with guest VMs using virtio-fs, a high-performance paravirtualized filesystem.

Overview

Shared directories allow your guest VM to access files from the host system:

• Real-time access: Guest sees host file changes immediately
• Bidirectional: Changes in guest persist to host (with ReadWrite mode)
• High performance: Uses virtio-fs for near-native file access speeds
• Secure: Guest cannot traverse outside the shared directory

Basic Usage

Use the .share() method on the VM builder to add a shared directory:

use capsa::{Capsa, LinuxVmConfig, MountMode};

let vm = Capsa::vm(LinuxVmConfig::new(kernel, rootfs))
    .share("/path/on/host", "myshare", MountMode::ReadWrite)
    .start()
    .await?;

The three arguments are:

1. Host path: The directory on the host to share
2. Tag: A unique identifier used when mounting in the guest
3. Mount mode: ReadOnly or ReadWrite

Mounting in Guest

After the VM boots, you must manually mount the shared directory in the guest. Use the tag you specified when calling .share():

use capsa::{Capsa, LinuxVmConfig, MountMode};
use std::time::Duration;

let vm = Capsa::vm(LinuxVmConfig::new(kernel, rootfs))
    .share("/home/user/project", "code", MountMode::ReadOnly)
    .console()
    .start()
    .await?;

let console = vm.console().unwrap();
console.wait_for_boot(Duration::from_secs(30)).await?;

// Mount the shared directory
console.exec(
    "mkdir -p /mnt/code && mount -t virtiofs code /mnt/code",
    Duration::from_secs(5)
).await?;

// Now the guest can access files at /mnt/code
console.exec("ls /mnt/code", Duration::from_secs(5)).await?;

TIP

Auto-mounting is planned for a future release as part of the Sandbox feature. For now, explicit mount commands are required.

Mount Modes

ReadOnly

The guest can read files but cannot modify them:

.share("/path/to/source", "src", MountMode::ReadOnly)

Use ReadOnly when:

• Sharing source code for compilation
• Passing configuration files
• The guest should not modify host files

ReadWrite

The guest can read and write files:

.share("/path/to/output", "output", MountMode::ReadWrite)

Use ReadWrite when:

• The guest needs to produce output files
• Running build processes that generate artifacts
• Interactive development workflows

Multiple Shares

You can add multiple shared directories with different tags:

let vm = Capsa::vm(LinuxVmConfig::new(kernel, rootfs))
    .share("/home/user/project/src", "source", MountMode::ReadOnly)
    .share("/home/user/project/build", "build", MountMode::ReadWrite)
    .share("/home/user/data", "data", MountMode::ReadOnly)
    .console()
    .start()
    .await?;

let console = vm.console().unwrap();
console.wait_for_boot(Duration::from_secs(30)).await?;

// Mount all shares
console.exec("mkdir -p /src && mount -t virtiofs source /src", Duration::from_secs(5)).await?;
console.exec("mkdir -p /build && mount -t virtiofs build /build", Duration::from_secs(5)).await?;
console.exec("mkdir -p /data && mount -t virtiofs data /data", Duration::from_secs(5)).await?;

Use Cases

Compiling Code in VM

Share source code read-only and output directory read-write:

let vm = Capsa::vm(LinuxVmConfig::new(kernel, rootfs))
    .share("/home/user/myproject", "project", MountMode::ReadOnly)
    .share("/tmp/build-output", "output", MountMode::ReadWrite)
    .console()
    .start()
    .await?;

// After mounting...
console.exec("cd /mnt/project && cargo build --target-dir /mnt/output", timeout).await?;

Processing Files

Pass input files to a guest process and retrieve results:

let vm = Capsa::vm(LinuxVmConfig::new(kernel, rootfs))
    .share("/path/to/input", "input", MountMode::ReadOnly)
    .share("/path/to/output", "output", MountMode::ReadWrite)
    .console()
    .start()
    .await?;

// After mounting...
console.exec("process-tool /mnt/input/data.json > /mnt/output/result.json", timeout).await?;

Development Workflow

Share your entire project directory for interactive development:

let vm = Capsa::vm(LinuxVmConfig::new(kernel, rootfs))
    .share("/home/user/workspace", "workspace", MountMode::ReadWrite)
    .console()
    .start()
    .await?;

Platform Support

Platform Limitations

Shared directories have different levels of support across platforms.

Platform	Status	Notes
Linux (KVM)	Full support	Uses virtiofsd
macOS	Not Yet	Planned for future release

On macOS, shared directory support is planned for a future release.

Security Considerations

When using shared directories, keep these security practices in mind:

• Use ReadOnly when possible: Only grant write access when the guest genuinely needs to modify files

• Limit shared scope: Share specific subdirectories rather than broad paths like home directories

• Avoid sensitive directories: Do not share directories containing secrets, credentials, or sensitive configuration

• Guest isolation: The guest cannot access files outside the shared directory boundaries, but any process in the guest can access the shared files

// Prefer this - specific directory
.share("/home/user/project/src", "src", MountMode::ReadOnly)

// Avoid this - too broad
.share("/home/user", "home", MountMode::ReadWrite)