Jose Jimenez
Jose Jimenez
Software Architect & Developer
> >

Fixing macOS Sequoia 15.5 Vagrant Shared Folder Issues with Laravel Homestead

Published in homestead, Laravel, macOS, Vagrant on May 29, 2025

If you're running Laravel Homestead (or other Vagrant setups) on macOS Sequoia 15.5 and experiencing shared folder disconnections after periods of inactivity, you're not alone. This article covers a systematic solution to keep your Vagrant shared folders alive and prevent the frustrating "shares stop working" issue.

The Problem

macOS Sequoia 15.5 introduced changes to power management and network handling that cause Vagrant shared folders to disconnect when idle for extended periods. This particularly affects:

  • Laravel Homestead users with Parallels
  • Potentially VirtualBox users (unconfirmed but likely)
  • Any Vagrant setup using NFS, SMB, or similar network-based shares

Symptoms

  • Shared folders work initially after vagrant up
  • After 10-30 minutes of inactivity, file access fails
  • Need to restart Vagrant VM to restore share functionality
  • Development workflow disrupted by frequent disconnections

The Solution: Systemd Keep-Alive Service

The most reliable fix is creating a systemd service that periodically accesses the shared folder, preventing the connection from timing out.

Step 1: Create the Systemd Service

SSH into your Vagrant box and create the service file:

1sudo nano /etc/systemd/system/vagrant-share-keepalive.service

Add the following content:

 1[Unit]
 2Description=Keep Vagrant shares alive
 3After=multi-user.target
 4 
 5[Service]
 6Type=simple
 7ExecStart=/bin/bash -c 'while true; do ls /var/www >/dev/null 2>&1; sleep 30; done'
 8Restart=always
 9User=vagrant
10RestartSec=5
11 
12[Install]
13WantedBy=multi-user.target

Important: Replace /var/www with your actual shared folder path. Common paths include:

  • /vagrant (default Vagrant share)
  • /var/www (common for web development)
  • /home/vagrant/code (Laravel Homestead default)

Step 2: Enable and Start the Service

1# Reload systemd configuration
2sudo systemctl daemon-reload
3 
4# Enable service to start on boot
5sudo systemctl enable vagrant-share-keepalive.service
6 
7# Start the service immediately
8sudo systemctl start vagrant-share-keepalive.service

Step 3: Verify It's Working

Check the service status:

1sudo systemctl status vagrant-share-keepalive.service

Monitor the logs to confirm activity:

1sudo journalctl -u vagrant-share-keepalive.service -f

You should see periodic activity indicating the service is accessing your shared folder.

Automation with Build Scripts

For automated deployments, you can create a shell script to set up the service:

 1#!/bin/bash
 2# setup-vagrant-keepalive.sh
 3 
 4SHARE_PATH="${1:-/var/www}"  # Default to /var/www, accept as parameter
 5INTERVAL="${2:-30}"          # Default to 30 seconds
 6 
 7echo "Setting up Vagrant share keep-alive service..."
 8 
 9# Create the systemd service file
10sudo tee /etc/systemd/system/vagrant-share-keepalive.service > /dev/null <<EOF
11[Unit]
12Description=Keep Vagrant shares alive
13After=multi-user.target
14 
15[Service]
16Type=simple
17ExecStart=/bin/bash -c 'while true; do ls $SHARE_PATH >/dev/null 2>&1; sleep $INTERVAL; done'
18Restart=always
19User=vagrant
20RestartSec=5
21 
22[Install]
23WantedBy=multi-user.target
24EOF
25 
26# Enable and start the service
27sudo systemctl daemon-reload
28sudo systemctl enable vagrant-share-keepalive.service
29sudo systemctl start vagrant-share-keepalive.service
30 
31echo "✅ Keep-alive service is running"

Usage:

1# Default settings
2./setup-vagrant-keepalive.sh
3 
4# Custom path and interval
5./setup-vagrant-keepalive.sh /home/vagrant/code 15

How It Works

The solution works by:

  1. Periodic Access: The ls command accesses the shared folder every 30 seconds
  2. Network Keep-Alive: Each access forces the OS to verify the mount is active
  3. Connection Refresh: Prevents macOS from marking the connection as idle
  4. Automatic Recovery: Systemd restarts the service if it fails

Troubleshooting

Permission Issues

If you encounter permission errors, try:

1# Use stat instead of ls (requires fewer permissions)
2ExecStart=/bin/bash -c 'while true; do stat /var/www >/dev/null 2>&1; sleep 30; done'
3 
4# Or change the user
5User=www-data

Service Won't Start

Check systemd logs:

1sudo journalctl -u vagrant-share-keepalive.service --no-pager

Verify your shared folder path exists:

1ls -la /var/www  # or your actual path

Still Experiencing Issues

  1. Verify your actual shared folder path with: mount | grep -E "(nfs|cifs|smb|vboxsf)"
  2. Try reducing the sleep interval to 15 seconds
  3. Consider using touch /path/to/share/.keepalive instead of ls

Laravel Homestead Specifics

For Laravel Homestead users, the default shared folder is typically /home/vagrant/code. Update your service accordingly:

1ExecStart=/bin/bash -c 'while true; do ls /home/vagrant/code >/dev/null 2>&1; sleep 30; done'

Impact and Performance

This solution:

  • Minimal CPU usage: Simple ls command every 30 seconds
  • No disk writes: Only reads directory information
  • Automatic startup: Runs on VM boot via systemd
  • Fault tolerant: Auto-restarts if the process fails

Conclusion

This macOS Sequoia 15.5 shared folder issue affects many Vagrant users, particularly those using Laravel Homestead with Parallels. The systemd keep-alive service provides a robust, automated solution that runs in the background without impacting development workflow.

While this workaround addresses the symptom rather than the root cause, it effectively prevents the frustrating share disconnections that disrupt development productivity. Hopefully, future updates to macOS, Parallels, or Vagrant will address the underlying issue.

Tested Environment:

  • macOS Sequoia 15.5
  • Laravel Homestead
  • Parallels Desktop 20
  • Ubuntu guest VM with systemd