diff --git a/ai-hub/app/api/routes/nodes.py b/ai-hub/app/api/routes/nodes.py
index da107fb..cb29710 100644
--- a/ai-hub/app/api/routes/nodes.py
+++ b/ai-hub/app/api/routes/nodes.py
@@ -399,6 +399,8 @@
    ./run.sh
    ```
 
+*Note for Mac users:* You can also double-click the `run_mac.command` file to start the node directly.
+
 ### Windows
 1. Open the folder in File Explorer.
 2. Double-click `run.bat`.
@@ -419,11 +421,19 @@
 # Cortex Agent Node — Seamless Runner
 set -e
 
+# Ensure we are in the script's directory (crucial for double-clicking on Mac)
+cd "$(dirname "$0")"
+
 echo "🚀 Starting Cortex Agent Node..."
 
 # 1. Environment Check
 if ! command -v python3 &> /dev/null; then
     echo "❌ Error: python3 is not installed. Please install Python 3.10+ and try again."
+    # Mac users often need to be pointed to python.org or brew
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        echo "💡 Tip: Visit https://www.python.org/downloads/macos/ or run 'brew install python'"
+    fi
+    sleep 5
     exit 1
 fi
 
@@ -432,7 +442,11 @@
 if [ ! -d "$VENV" ]; then
     echo "[*] Creating virtual environment..."
     python3 -m venv "$VENV" || {
-        echo "❌ Error: Failed to create virtual environment. If you are on Ubuntu/Debian, try: sudo apt install python3-venv"
+        echo "❌ Error: Failed to create virtual environment."
+        if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+            echo "💡 Tip: Try: sudo apt install python3-venv"
+        fi
+        sleep 5
         exit 1
     }
 fi
@@ -449,7 +463,7 @@
 # 4. Playwright Setup (for Browser Skills)
 if grep -q "playwright" requirements.txt; then
     if [ ! -f "$VENV/.playwright-installed" ]; then
-        echo "[*] Installing browser engines and system dependencies (may require sudo)..."
+        echo "[*] Installing browser engines and system dependencies..."
         # --with-deps ensures chromium actually runs on Linux (installs missing .so files)
         if [[ "$OSTYPE" == "linux-gnu"* ]]; then
              python3 -m playwright install --with-deps chromium
@@ -463,8 +477,14 @@
 # 5. Start the Node
 echo "✅ Environment ready. Booting node..."
 python3 -m agent_node.main
+if [ $? -ne 0 ]; then
+    echo "⚠️ Node exited with error. Check the logs above."
+    sleep 5
+fi
 """
 
+    RUN_MAC_CONTENT = RUN_SH_CONTENT # They are compatible, .command just helps macOS users
+
     RUN_BAT_CONTENT = """@echo off
 echo 🚀 Starting Cortex Agent Node...
 python --version >nul 2>&1
@@ -559,7 +579,7 @@
             # 3. Add the generated config YAML as 'agent_config.yaml'
             zip_file.writestr("agent_config.yaml", config_yaml)
             
-            # 4. Add README and run.sh / run.bat
+            # 4. Add README and run.sh / run.bat / run_mac.command
             zip_file.writestr("README.md", README_CONTENT)
             
             # Create run.sh with execute permissions (external_attr)
@@ -568,6 +588,12 @@
             run_sh_info.compress_type = zipfile.ZIP_DEFLATED
             zip_file.writestr(run_sh_info, RUN_SH_CONTENT)
 
+            # Create run_mac.command (Mac double-clickable)
+            run_mac_info = zipfile.ZipInfo("run_mac.command")
+            run_mac_info.external_attr = 0o100755 << 16 # -rwxr-xr-x
+            run_mac_info.compress_type = zipfile.ZIP_DEFLATED
+            zip_file.writestr(run_mac_info, RUN_MAC_CONTENT)
+
             # Create run.bat
             zip_file.writestr("run.bat", RUN_BAT_CONTENT)