Linsk Manager for macOS

A convenient bash wrapper for Linsk that automates the process of mounting Linux partitions on macOS. It supports LUKS.

Linsk is a stable tool that uses a lightweight Alpine VM to access Linux filesystems. However, running it manually requires finding the disk identifier, checking partitions, and manually connecting to the network share via Finder. This script automates the entire workflow and, most importantly, ensures safe data flushing to prevent data loss when unmounting.

✨ Features

• Auto-detects Linux partitions: Automatically finds external physical disks with Linux partitions.
• Auto-detects LUKS encryption: Reads the partition header. If LUKS is detected, it securely prompts for the password and passes it to Linsk.
• Auto-mounts in Finder: Intercepts the AFP share credentials from Linsk's logs and automatically mounts the network drive in Finder.
• Safe Data Flush: Guarantees data integrity by forcing macOS to flush its network cache before terminating the Linsk VM, whether you press Ctrl+C or eject the drive in Finder.
• Single Instance Lock: Prevents multiple instances from running simultaneously and causing device passthrough conflicts.
• Root Privilege Isolation: Drops sudo privileges where unnecessary (e.g., GUI operations) following the principle of least privilege.

📋 Prerequisites

1. macOS (Intel or Apple Silicon)
2. Linsk installed: You must have Linsk installed. See the official Linsk documentation.
3. Administrator privileges: The script must be run with sudo because Linsk requires raw block device passthrough.

🚀 Usage

1. Download the script:

   curl -O https://github.com/ghraw/jsfan3/linsk-manager/main/linsk_manager.sh
   chmod +x linsk_manager.sh

2. Connect your external Linux drive.
3. Run the script with sudo:

   sudo ./linsk_manager.sh

4. If the drive is LUKS-encrypted, you will be prompted to enter the decryption password.
5. The script will boot the VM, mount the partition, and automatically open the network share in Finder.

🛑 How to close safely

You have two ways to close the script, both are safe:

• Method 1 (Recommended): Eject the linsk network drive in Finder (Right-click -> Eject). The script will detect the ejection and shut down the VM automatically.
• Method 2: Press Ctrl+C in the terminal. The script will intercept the interrupt, force macOS to flush all pending data to the VM, and only then terminate Linsk.

📺 Example Output

Here is an example of what you will see when running the script with a LUKS-encrypted drive and safely closing it with Ctrl+C or using EJECT in Finder:

% sudo ./linsk_manager.sh
=========================================================================
linsk source code and documentation: https://github.com/AlexSSD7/linsk
script created by Francesco Galgani: https://www.informatica-libera.net
=========================================================================
>>> DISCLAIMER: This script does not support LVM volumes.

>>> TIP: If Finder shows empty folders, Spotlight indexing might be
    blocking the view. Go to 'System Settings > Siri & Spotlight >
    Spotlight Privacy' and add the 'linsk' network folder there.
=========================================================================

[INFO] Searching for Linux partitions on external disks...
[INFO] Checking partition type (LUKS vs standard)...
[INFO] LUKS encryption detected.

[INFO] Starting linsk...
================================================================================
    To safely close: EJECT the 'linsk' drive in Finder (Right-click -> Eject).
    The script will detect it and shut down automatically.

    As an alternative, you can simply press Ctrl+C.
    The script will automatically flush data and unmount the drive safely.
================================================================================

time=2026-07-26T18:51:55.654+02:00 level=WARN msg="Using raw block device passthrough. Please note that it's YOUR responsibility to ensure that no device is mounted in your OS and the VM at the same time. Otherwise, you run serious risks. No further warnings will be issued." caller=vm
time=2026-07-26T18:51:55.669+02:00 level=INFO msg="Booting the VM" caller=vm
time=2026-07-26T18:52:06.684+02:00 level=INFO msg="The VM is up, setting it up" caller=vm
time=2026-07-26T18:52:10.062+02:00 level=INFO msg="The VM is ready" caller=vm
time=2026-07-26T18:52:10.324+02:00 level=INFO msg="Mounting the device" dev=vdb fs=<auto> luks=true
time=2026-07-26T18:52:10.409+02:00 level=INFO msg="Attempting to open a LUKS device" caller=file-manager vm-path=/dev/vdb
Enter Password: 
time=2026-07-26T18:52:25.081+02:00 level=INFO msg="LUKS device opened successfully" caller=file-manager vm-path=/dev/vdb
time=2026-07-26T18:52:25.869+02:00 level=INFO msg="Started the network share successfully" backend=afp
===========================
[Network File Share Config]
The network file share was started. Please use the credentials below to connect to the file server.

Type: AFP
URL: afp://127.0.0.1:9000/linsk
Username: linsk
Password: 416HJ3705ElN92p8
===========================

[INFO] AFP Share credentials detected: 416HJ3705ElN92p8. Mounting in Finder...
[INFO] Finder window should open shortly.

Option 1) After CTRL+C:

[INFO] Script interrupted. Cleaning up...
[INFO] Forcing unmount of /Volumes/linsk to flush network cache...
Unmount successful for /Volumes/linsk
[INFO] Terminating linsk and VM...
[INFO] Done. You can safely disconnect your disk.

Option 2) EJECT in Finder

[INFO] Network drive ejected. Terminating linsk and VM safely...
time=2026-07-26T19:52:16.939+02:00 level=WARN msg="Caught interrupt, safely shutting down" signal=interrupt
time=2026-07-26T19:52:16.939+02:00 level=WARN msg="Canceling the VM context" caller=vm
time=2026-07-26T19:52:17.003+02:00 level=WARN msg="Sending poweroff command to the VM" caller=vm
time=2026-07-26T19:52:17.017+02:00 level=INFO msg="Shutting the VM down safely" caller=vm

[INFO] Script interrupted. Cleaning up...

⚠️ Troubleshooting & Tips

• Empty folders in Finder: macOS Spotlight indexing might block the view of network folders. If you see the drive mounted but folders are empty, go to System Settings > Siri & Spotlight > Spotlight Privacy and drag the linsk network folder there to prevent indexing issues.
• "disk not readable" popup: If macOS shows this popup when you connect the physical drive, click Ignore. The script handles the disk directly.
• LVM not supported: This script is designed for standard ext4 or LUKS partitions. It does not currently support LVM (Logical Volume Manager).

📜 License

This script is licensed under the CC0 1.0 Universal (Public Domain). Feel free to use, modify, and distribute it.

🙏 Credits

• Linsk creator: AlexSSD7 for building the underlying tool.
• Script author: Francesco Galgani (informatica-libera.net)