Mac Host. Linux Development Flow.

• Hardware: A modern Apple Silicon Mac running macOS.
• Storage: At least 20GB of free drive space (Less required for Headless-only setups).
• Permissions: Admin access for Network/Sharing settings.

The core objective is to decouple the Development Workflow from the Operating System. We treat the machine as two distinct entities working in tandem.

The foundational goal is to maintain the reliability of modern Apple Silicon and the macOS ecosystem for everyday use, while leveraging a Linux VM for development tasks.

• Host Integrity: We keep macOS as the stable host for critical functions (Hardware drivers, Battery life, Wi-Fi stability) and high-performance native apps (Zoom, Teams, Office).
• VM Performance: We ensure the Linux environment remains lightweight and disposable.

To ensure a seamless flow, macFlow uses standard protocols to bypass driver limitations on Apple Silicon:

• Files: macOS ~/macFlow directory is mounted into the VM via SSHFS.
• Clipboard: Copy/Paste is handled via SPICE (Desktop Mode) or SSH (Headless Mode).
• Identity: Git credentials are passed via SSH Agent Forwarding.

We connect the Host and Guest via a network bridge rather than fragile virtualization drivers.

macFlow supports two distinct operating modes.

• What it is: No Linux GUI. You use macOS native terminals (Ghostty/Kitty) and VSCode Remote to interact with the Linux engine.
• Pros: Extremely lightweight, max battery efficiency, zero maintenance, native macOS fonts/rendering.
• Cons: No tiling window manager logic; relies on macOS window management.

• What it is: A full Tiling Window Manager environment inside the VM.
• Pros: The complete tiling experience (Dwindle layout), distraction-free focus.
• Cons: Higher resource usage.

Note: For the desktop philosophy see macFlow Desktop.

Every macFlow build requires these core steps:

• VM Platform: UTM Setup
• Guest OS:
  • Arch Linux Installation
  • Arch Linux Configuration
• Integration: "Headless" Bridge Setup

• Tiling Window Manager

Install the tools to enable efficient development work.

• Development Tools: VSCode, git config, etc.

macFlow/
├── docs/               # Documentation
│   ├── Guest-OS/       # Arch Linux installation and configuration
│   ├── Integration/    # SSH, SSHFS, and Bridge configuration
│   ├── Tools/          # VSCode, git config, etc.
│   ├── VM/             # UTM configuration
│   └── WM/             # Hyprland and Waybar configuration
├── dotfiles/           # Source configuration files (Stow targets)
├── LICENSE             # Source Code License (MIT)
├── LICENSE-DOCS.md     # Documentation License (CC BY 4.0)
└── README.md           # You are here