From 672ed2bc24bc095334be72e790b59b7fab4742d0 Mon Sep 17 00:00:00 2001
From: Ryan <221235059+rwilliamspbg-ops@users.noreply.github.com>
Date: Sat, 11 Jul 2026 01:29:52 +0000
Subject: [PATCH 1/2] Fix devcontainer setup and one-click GUI full-stack
 launch

---
 .devcontainer/Dockerfile        |   8 +-
 .devcontainer/devcontainer.json |  13 +++-
 .devcontainer/post_create.sh    | 126 +++++++++++++++++++++++---------
 docker-compose.dev.yml          |  94 +++++++++++++++++++++++-
 docker-compose.yml              |  42 +++++++++++
 launch.py                       |  46 ++++++++----
 launch.sh                       |   2 +-
 mohawk_gui/main_window.py       |  20 +++--
 8 files changed, 288 insertions(+), 63 deletions(-)

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index b08233e..ec54f96 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -4,8 +4,10 @@ ENV DEBIAN_FRONTEND=noninteractive
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     build-essential cmake git ca-certificates wget curl pkg-config \
-    python3 python3-pip python3-venv python3-dev ca-certificates \
-    libssl-dev libffi-dev && \
+    python3 python3-pip python3-venv python3-dev python-is-python3 \
+    sudo lsof net-tools \
+    libssl-dev libffi-dev \
+    libgl1 libegl1 libxkbcommon-x11-0 libdbus-1-3 xauth && \
     rm -rf /var/lib/apt/lists/*
 
 # Install liboqs from source
@@ -13,7 +15,7 @@ WORKDIR /opt
 RUN git clone --depth 1 https://github.com/open-quantum-safe/liboqs.git && \
     mkdir -p liboqs/build && cd liboqs/build && \
     cmake -DCMAKE_BUILD_TYPE=Release .. && \
-    make -j"$(nproc)" && make install
+    make -j"$(nproc)" && make install && ldconfig
 
 # Ensure pip is upgraded and install Python oqs wrapper
 RUN python3 -m pip install --upgrade pip setuptools wheel && \
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 8d408ef..b4857e5 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -3,9 +3,16 @@
   "build": {
     "dockerfile": "Dockerfile"
   },
-  "workspaceFolder": "/workspace",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+  },
   "settings": {},
-  "extensions": [],
+  "extensions": [
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "ms-azuretools.vscode-docker"
+  ],
   "forwardPorts": [8003],
-  "postCreateCommand": "./.devcontainer/post_create.sh"
+  "postCreateCommand": "bash .devcontainer/post_create.sh"
 }
diff --git a/.devcontainer/post_create.sh b/.devcontainer/post_create.sh
index 6f96305..f5eca5e 100644
--- a/.devcontainer/post_create.sh
+++ b/.devcontainer/post_create.sh
@@ -1,36 +1,96 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-echo "Running devcontainer post-create: install build deps and liboqs"
-# install system deps (attempt apt, then apk)
-if command -v apt-get >/dev/null 2>&1; then
-  sudo apt-get update
-  sudo apt-get install -y build-essential cmake git python3-dev python3-pip pkg-config
-elif command -v apk >/dev/null 2>&1; then
-  sudo apk add --no-cache build-base cmake git python3 python3-dev py3-pip pkgconfig
-else
-  echo "Unknown package manager; please install build tools (cmake, make, git, python3-dev) manually"
-fi
-
-CACHE_DIR="$HOME/.cache/liboqs"
-mkdir -p "$CACHE_DIR"
-if [ ! -d "$CACHE_DIR/liboqs" ]; then
-  git clone --depth 1 https://github.com/open-quantum-safe/liboqs.git "$CACHE_DIR/liboqs"
-fi
-
-pushd "$CACHE_DIR/liboqs"
-mkdir -p build && cd build
-cmake -DCMAKE_BUILD_TYPE=Release ..
-make -j"$(nproc)"
-if command -v sudo >/dev/null 2>&1; then
-  sudo make install
-else
-  make install
-fi
-popd
-
-# ensure pip and install oqs python package
-python3 -m pip install --upgrade pip || true
-python3 -m pip install oqs || true
-
-echo "post-create complete"
+echo "[devcontainer] Running post-create setup"
+
+run_as_root() {
+  if [ "$(id -u)" -eq 0 ]; then
+    "$@"
+  elif command -v sudo >/dev/null 2>&1; then
+    sudo "$@"
+  else
+    echo "[WARN] Need root privileges for: $*"
+    return 1
+  fi
+}
+
+install_system_deps() {
+  if command -v apt-get >/dev/null 2>&1; then
+    run_as_root apt-get update
+    run_as_root apt-get install -y \
+      build-essential cmake git python3-dev python3-pip python3-venv pkg-config \
+      libgl1 libegl1 libxkbcommon-x11-0 libdbus-1-3 lsof net-tools
+  elif command -v apk >/dev/null 2>&1; then
+    run_as_root apk add --no-cache \
+      build-base cmake git python3 python3-dev py3-pip py3-virtualenv pkgconfig \
+      mesa-gl libxkbcommon dbus-libs lsof net-tools
+  else
+    echo "[WARN] Unsupported package manager; skipping system package install"
+  fi
+}
+
+ensure_liboqs() {
+  if [ "${MOHAWK_SKIP_LIBOQS_BUILD:-0}" = "1" ]; then
+    echo "[devcontainer] Skipping liboqs build (MOHAWK_SKIP_LIBOQS_BUILD=1)"
+    return
+  fi
+
+  if pkg-config --exists liboqs 2>/dev/null || [ -f /usr/local/lib/liboqs.so ] || [ -f /usr/local/lib64/liboqs.so ]; then
+    echo "[devcontainer] liboqs already installed"
+    return
+  fi
+
+  echo "[devcontainer] liboqs not found; building from source"
+  local cache_dir="$HOME/.cache/liboqs"
+  mkdir -p "$cache_dir"
+
+  if [ ! -d "$cache_dir/liboqs/.git" ]; then
+    rm -rf "$cache_dir/liboqs"
+    git clone --depth 1 https://github.com/open-quantum-safe/liboqs.git "$cache_dir/liboqs"
+  fi
+
+  pushd "$cache_dir/liboqs" >/dev/null
+  mkdir -p build
+  cd build
+  cmake -DCMAKE_BUILD_TYPE=Release ..
+  make -j"$(nproc)"
+  run_as_root make install
+  run_as_root ldconfig || true
+  popd >/dev/null
+}
+
+install_python_deps() {
+  if [ "${MOHAWK_SKIP_PY_DEPS:-0}" = "1" ]; then
+    echo "[devcontainer] Skipping Python dependency install (MOHAWK_SKIP_PY_DEPS=1)"
+    return
+  fi
+
+  cd "${WORKSPACE_FOLDER:-$PWD}"
+  if [ ! -f requirements.txt ]; then
+    echo "[WARN] requirements.txt not found; skipping Python dependency install"
+    return
+  fi
+
+  if [ ! -d .venv ]; then
+    python3 -m venv .venv
+  fi
+
+  # shellcheck disable=SC1091
+  source .venv/bin/activate
+  python -m pip install --upgrade pip setuptools wheel
+  python -m pip install -r requirements.txt
+
+  # Optional OQS wrapper used by secure flows.
+  python -m pip install oqs || echo "[WARN] oqs Python wrapper installation failed; continuing"
+
+  python - <<'PY'
+import fastapi, uvicorn, requests, psutil  # noqa: F401
+print("[devcontainer] Core Python dependencies imported successfully")
+PY
+}
+
+install_system_deps
+ensure_liboqs
+install_python_deps
+
+echo "[devcontainer] post-create complete"
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 61d27e3..8183044 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -40,8 +40,100 @@ services:
       context: .
       dockerfile: Dockerfile.worker
     ports:
-      - "8003:8000"
+      - "8005:8000"
     environment:
       - PORT=8000
       - HOST=0.0.0.0
     command: python prototype/worker.py --host 0.0.0.0 --port 8000
+
+  mohawk-gui:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: mohawk-gui-dev
+    ports:
+      - "8003:8003"
+    volumes:
+      - ./mohawk_gui:/app/mohawk_gui
+      - ./certs:/app/certs
+      - ./logs:/app/logs
+    environment:
+      - PYTHONUNBUFFERED=1
+      - PYTHONDONTWRITEBYTECODE=1
+      - QT_QPA_PLATFORM=offscreen
+      - DISCOVERY=true
+    command: >
+      python -m uvicorn prototype.gui_backend:app
+      --host 0.0.0.0 --port 8003
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8003/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    restart: unless-stopped
+
+  mohawk-worker:
+    build:
+      context: .
+      dockerfile: Dockerfile.worker
+    container_name: mohawk-worker-dev
+    ports:
+      - "8004:8003"
+    volumes:
+      - ./models:/app/models
+      - ./certs:/app/certs
+      - ./logs:/app/logs
+    environment:
+      - PYTHONUNBUFFERED=1
+      - PYTHONDONTWRITEBYTECODE=1
+      - QT_QPA_PLATFORM=offscreen
+      - DISCOVERY=true
+    command: >
+      python -m uvicorn prototype.worker_secure:app
+      --host 0.0.0.0 --port 8003
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8003/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+
+  mohawk-desktop-gui:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: mohawk-desktop-gui-dev
+    depends_on:
+      - mohawk-gui
+      - mohawk-worker
+    environment:
+      - PYTHONUNBUFFERED=1
+      - PYTHONDONTWRITEBYTECODE=1
+      - DISPLAY=${DISPLAY}
+      - QT_QPA_PLATFORM=xcb
+      - MOHAWK_SKIP_DESKTOP_GUI=${MOHAWK_SKIP_DESKTOP_GUI:-0}
+      - MOHAWK_GUI_SERVICE_URL=http://host.docker.internal:8003
+      - MOHAWK_WORKER_SERVICE_URL=http://host.docker.internal:8004
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - /tmp/.X11-unix:/tmp/.X11-unix:rw
+      - ./certs:/app/certs
+      - ./logs:/app/logs
+    command: >
+      sh -c '
+      if [ "$$MOHAWK_SKIP_DESKTOP_GUI" = "1" ]; then
+        echo "Desktop GUI launch was skipped by the launcher.";
+        exit 0;
+      fi;
+      if [ -z "$$DISPLAY" ]; then
+        echo "DISPLAY is not set; skipping desktop GUI launch.";
+        exit 0;
+      fi;
+      until curl -fsS http://host.docker.internal:8003/health >/dev/null 2>&1; do
+        echo "Waiting for GUI backend...";
+        sleep 2;
+      done;
+      python mohawk_gui/main.py --port 8003
+      '
+    restart: "no"
diff --git a/docker-compose.yml b/docker-compose.yml
index 41e8b6c..f9033f0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -56,6 +56,48 @@ services:
     networks:
       - mohawk-network
 
+  mohawk-desktop-gui:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: mohawk-desktop-gui
+    depends_on:
+      - mohawk-gui
+      - mohawk-worker
+    environment:
+      - PYTHONUNBUFFERED=1
+      - PYTHONDONTWRITEBYTECODE=1
+      - DISPLAY=${DISPLAY}
+      - QT_QPA_PLATFORM=xcb
+      - MOHAWK_SKIP_DESKTOP_GUI=${MOHAWK_SKIP_DESKTOP_GUI:-0}
+      - MOHAWK_GUI_SERVICE_URL=http://host.docker.internal:8003
+      - MOHAWK_WORKER_SERVICE_URL=http://host.docker.internal:8004
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - /tmp/.X11-unix:/tmp/.X11-unix:rw
+      - ./certs:/app/certs
+      - ./logs:/app/logs
+    command: >
+      sh -c '
+      if [ "$$MOHAWK_SKIP_DESKTOP_GUI" = "1" ]; then
+        echo "Desktop GUI launch was skipped by the launcher.";
+        exit 0;
+      fi;
+      if [ -z "$$DISPLAY" ]; then
+        echo "DISPLAY is not set; skipping desktop GUI launch.";
+        exit 0;
+      fi;
+      until curl -fsS http://host.docker.internal:8003/health >/dev/null 2>&1; do
+        echo "Waiting for GUI backend...";
+        sleep 2;
+      done;
+      python mohawk_gui/main.py --port 8003
+      '
+    restart: "no"
+    networks:
+      - mohawk-network
+
 networks:
   mohawk-network:
     name: mohawk-network
diff --git a/launch.py b/launch.py
index 1803295..eee553b 100755
--- a/launch.py
+++ b/launch.py
@@ -248,10 +248,12 @@ def launch_docker_stack():
 
     print(f"{WHITE}Executing: {GOLD}docker compose up -d --build{RESET}")
     try:
-        res = subprocess.run(["docker", "compose", "up", "-d"], capture_output=False)
+        compose_env = os.environ.copy()
+        compose_env["MOHAWK_SKIP_DESKTOP_GUI"] = "1"
+        res = subprocess.run(["docker", "compose", "up", "-d"], capture_output=False, env=compose_env)
         if res.returncode != 0:
             print(f"{GOLD}[INFO] 'docker compose' returned an error. Retrying with legacy 'docker-compose'...{RESET}")
-            subprocess.run(["docker-compose", "up", "-d"])
+            subprocess.run(["docker-compose", "up", "-d"], env=compose_env)
 
         print(f"\n{WHITE}Monitoring container boot health...{RESET}")
 
@@ -273,6 +275,7 @@ def launch_docker_stack():
             print(f"  • GUI backend running at: {CYAN}http://localhost:8003{RESET}")
             print(f"  • Secure worker mapped at: {CYAN}http://localhost:8004{RESET}")
             print(f"  • View metrics endpoint:  {CYAN}http://localhost:8003/api/metrics{RESET}")
+            launch_desktop_gui("http://localhost:8003", "http://localhost:8004")
             print(f"\n{WHITE}To monitor logs: {GOLD}docker compose logs -f{RESET}")
             print(f"To shutdown stack: {CRIMSON}docker compose down{RESET}")
         else:
@@ -323,18 +326,7 @@ def launch_native_stack():
             print(f"  • GUI backend: {CYAN}http://localhost:8003{RESET}")
             print(f"  • Worker:      {CYAN}http://localhost:8004{RESET}")
             print(f"\n{WHITE}All services started in the background. Press CTRL+C or clean up to shut them down.{RESET}")
-
-            # Offer to launch the PyQt6 Desktop GUI
-            try:
-                import PyQt6
-                print_border("─", CYAN, 80)
-                choice = input(f"Would you like to open the Desktop GUI dashboard? (y/n) [y]: ").strip().lower()
-                if choice in ["", "y", "yes"]:
-                    print(f"{WHITE}Opening PyQt6 Dashboard...{RESET}")
-                    p_gui = subprocess.Popen([sys.executable, "mohawk_gui/main.py", "--port", "8003"])
-                    local_processes.append(p_gui)
-            except ImportError:
-                print(f"\n{GOLD}[INFO] PyQt6 is not installed or X11 environment not available. Web GUI and API services are still fully accessible at http://localhost:8003!{RESET}")
+            launch_desktop_gui()
         else:
             print(f"\n{CRIMSON}❌ Failed to bind to ports. Please check logs and try again.{RESET}")
             shutdown_local_stack()
@@ -365,6 +357,32 @@ def shutdown_local_stack():
     print(f"{EMERALD}[✓] All local processes terminated successfully.{RESET}")
 
 
+def launch_desktop_gui(gui_service_url="http://localhost:8003", worker_service_url="http://localhost:8004"):
+    """Launch the PyQt desktop dashboard if the environment supports it."""
+    try:
+        import PyQt6  # noqa: F401
+    except ImportError:
+        print(f"{GOLD}[INFO] PyQt6 is not installed, so the desktop GUI will not auto-launch.{RESET}")
+        print(f"{GOLD}       Install dependencies with 'pip install -r requirements.txt' or use launch.sh.{RESET}")
+        return
+
+    if sys.platform != "win32" and not os.environ.get("DISPLAY"):
+        print(f"{GOLD}[INFO] DISPLAY is not set, so the desktop GUI will not auto-launch in this session.{RESET}")
+        return
+
+    gui_env = os.environ.copy()
+    gui_env["MOHAWK_GUI_SERVICE_URL"] = gui_service_url
+    gui_env["MOHAWK_WORKER_SERVICE_URL"] = worker_service_url
+
+    print(f"{WHITE}Launching Desktop GUI dashboard...{RESET}")
+    try:
+        p_gui = subprocess.Popen([sys.executable, "mohawk_gui/main.py", "--port", "8003"], env=gui_env)
+        local_processes.append(p_gui)
+        print(f"{EMERALD}[✓] Desktop GUI launched successfully.{RESET}")
+    except Exception as e:
+        print(f"{CRIMSON}[ERROR] Failed to launch the desktop GUI: {e}{RESET}")
+
+
 def clean_environment():
     """Runs Docker and directory cleanups."""
     print_border("═", CYAN, 80)
diff --git a/launch.sh b/launch.sh
index 5f576f5..04c80b9 100755
--- a/launch.sh
+++ b/launch.sh
@@ -36,7 +36,7 @@ source venv/bin/activate || . venv/bin/activate
 
 # Check if packages are already installed to make boot sub-second
 echo -e "${WHITE}Verifying library dependencies...${RESET}"
-if ! python3 -c "import fastapi, uvicorn, requests, cryptography, zeroconf, psutil" &> /dev/null; then
+if ! python3 -c "import fastapi, uvicorn, requests, cryptography, zeroconf, psutil, PyQt6" &> /dev/null; then
     echo -e "${GOLD}[INFO] Missing packages detected. Installing required dependencies from requirements.txt...${RESET}"
     pip install --upgrade pip
     pip install -r requirements.txt
diff --git a/mohawk_gui/main_window.py b/mohawk_gui/main_window.py
index 35a793b..d1add6a 100644
--- a/mohawk_gui/main_window.py
+++ b/mohawk_gui/main_window.py
@@ -3,6 +3,7 @@
 """Mohawk Inference Engine - Live Wired GUI"""
 
 import json
+import os
 import sys
 from datetime import datetime
 
@@ -80,13 +81,18 @@ def __init__(self):
         self.setGeometry(100, 100, 1400, 900)
 
         # API endpoints
-        self.gui_service_url = "http://localhost:8003"
-        self.worker_service_url = "http://localhost:8004"
+        self.gui_service_url = os.environ.get("MOHAWK_GUI_SERVICE_URL", "http://localhost:8003")
+        self.worker_service_url = os.environ.get("MOHAWK_WORKER_SERVICE_URL", "http://localhost:8004")
+
+        # Status bar must exist before any tab initialization or background
+        # updates can try to write to it.
+        self.status_bar = QStatusBar()
+        self.setStatusBar(self.status_bar)
+        self.status_bar.showMessage("Ready - Connecting to Docker backend services...")
 
         # Health check thread
         self.health_thread = WorkerHealthCheck(self.gui_service_url)
         self.health_thread.health_updated.connect(self.on_health_update)
-        self.health_thread.start()
 
         # Central widget
         central_widget = QWidget()
@@ -150,16 +156,14 @@ def __init__(self):
         self.tabs.addTab(self.security_widget, "Security Center")
         self.tabs.addTab(self.history_widget, "History")
 
-        # Status bar
-        self.status_bar = QStatusBar()
-        self.setStatusBar(self.status_bar)
-        self.status_bar.showMessage("Ready - Connecting to Docker backend services...")
-
         # Timer for periodic updates
         self.update_timer = QTimer()
         self.update_timer.timeout.connect(self.periodic_update)
         self.update_timer.start(5000)  # Update every 5 seconds
 
+        # Start background health updates after the UI is fully initialized.
+        self.health_thread.start()
+
     def on_health_update(self, health_info):
         """Handle health check updates."""
         status = health_info.get("status")

From 17c1080c0dbcdb3cf402e010411f1b623305ea42 Mon Sep 17 00:00:00 2001
From: Ryan <221235059+rwilliamspbg-ops@users.noreply.github.com>
Date: Sat, 11 Jul 2026 01:39:19 +0000
Subject: [PATCH 2/2] Update README/install/setup docs and changelog

---
 CHANGELOG.md    | 37 ++++++++++++++++++++++++
 DOCKER_SETUP.md | 13 +++++++++
 INSTALL.md      | 66 ++++++++++++++++++++++++++++++++++++++++++
 QUICKSTART.md   | 50 +++++++++++++++++++++++++++++++-
 README.md       | 59 +++++++++++++++++++++++++-------------
 SETUP.md        | 76 +++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 280 insertions(+), 21 deletions(-)
 create mode 100644 INSTALL.md
 create mode 100644 SETUP.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc77bbb..b35887e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,43 @@
 
 All notable changes to the project will be documented in this file.
 
+## [2.1.1] - 2026-07-11
+
+### 🔧 Devcontainer and Setup Reliability
+
+- Updated `.devcontainer/devcontainer.json`:
+	- workspace path compatibility for Codespaces
+	- docker-outside-of-docker feature enablement
+	- Python and Docker VS Code extension recommendations
+	- explicit bash post-create invocation
+- Updated `.devcontainer/Dockerfile` with missing runtime and diagnostics packages.
+- Reworked `.devcontainer/post_create.sh` to be idempotent, root-safe, and configurable with:
+	- `MOHAWK_SKIP_LIBOQS_BUILD=1`
+	- `MOHAWK_SKIP_PY_DEPS=1`
+
+### 🖥️ Full-Stack Desktop GUI Launch Improvements
+
+- Fixed startup ordering in `mohawk_gui/main_window.py`:
+	- initialize status bar before tab refresh paths
+	- start background health thread only after UI widget initialization
+- Added environment-based backend URL overrides for desktop GUI runtime.
+- Added reusable desktop GUI launcher flow in `launch.py` for both native and Docker orchestration.
+- Updated `launch.sh` dependency probe to include `PyQt6`.
+- Added `mohawk-desktop-gui` service to `docker-compose.yml`.
+- Added full-stack parity services to `docker-compose.dev.yml` and adjusted conflicting host port mapping.
+
+### 📚 Documentation Updates
+
+- Updated `README.md` quick-start and documentation index.
+- Updated `QUICKSTART.md` with launcher/devcontainer paths and focused model/chat smoke checks.
+- Updated `DOCKER_SETUP.md` desktop GUI behavior notes and skip flag usage.
+- Added `INSTALL.md` and `SETUP.md` for clear install/runtime guidance.
+
+### ✅ Validation
+
+- End-to-end functional test executed: `python test_user_functions.py`.
+- Result: `33/33 passed (100.0%)` including model list/load and chat inference paths.
+
 ## [2.1.0] - 2024-01-15
 
 ### 🎉 Major Release: Professional Dashboard with LM Studio Features
diff --git a/DOCKER_SETUP.md b/DOCKER_SETUP.md
index 272814c..a83eb34 100644
--- a/DOCKER_SETUP.md
+++ b/DOCKER_SETUP.md
@@ -71,8 +71,21 @@ The GUI window will open and connect to the Docker-based backend services.
 |---------|------|----------|---------|
 | mohawk-gui | 8003 | Docker Container | Backend API & health endpoints |
 | mohawk-worker | 8004 | Docker Container | Inference worker service |
+| mohawk-desktop-gui | n/a | Docker Container | Desktop GUI launcher (display-dependent) |
 | PyQt6 GUI | (Local) | Your Machine | Desktop application interface |
 
+## Desktop GUI Launch Behavior
+
+- `docker compose up -d --build` includes `mohawk-desktop-gui` for one-click full-stack startup.
+- If `DISPLAY` is not set, the desktop GUI service exits cleanly and backend APIs continue running.
+- `launch.py` sets `MOHAWK_SKIP_DESKTOP_GUI=1` when orchestrating compose to avoid duplicate GUI instances, then launches host desktop GUI directly when supported.
+
+Skip container desktop GUI explicitly:
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
 ## Container Management
 
 ### View Container Logs
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..fb4249e
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,66 @@
+# Mohawk Inference Engine - Install Guide
+
+## Prerequisites
+
+- Python 3.10+
+- Git
+- Docker + Docker Compose (recommended for full stack)
+- Linux/macOS shell or PowerShell on Windows
+
+For desktop GUI launch on Linux, ensure display libraries and `DISPLAY` are available.
+
+## Clone
+
+```bash
+git clone https://github.com/rwilliamspbg-ops/Mohawk-Inference-Engine.git
+cd Mohawk-Inference-Engine
+```
+
+## Python Environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+## Optional: Devcontainer
+
+In VS Code:
+- Dev Containers: Rebuild and Reopen in Container
+
+Then run:
+
+```bash
+bash .devcontainer/post_create.sh
+```
+
+Fast smoke mode:
+
+```bash
+MOHAWK_SKIP_LIBOQS_BUILD=1 MOHAWK_SKIP_PY_DEPS=1 bash .devcontainer/post_create.sh
+```
+
+## Verify Install
+
+```bash
+python - <<'PY'
+import fastapi, uvicorn, requests, psutil
+print('Core dependencies OK')
+PY
+```
+
+## Next
+
+- Go to `SETUP.md` for runtime startup options.
+- Go to `QUICKSTART.md` for API smoke tests.
diff --git a/QUICKSTART.md b/QUICKSTART.md
index 3a46612..e939a36 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -15,7 +15,17 @@ Mohawk is a production-grade AI inference engine with:
 
 ---
 
-## Quick Start (Docker)
+## Quick Start Paths
+
+### A) One-Click Launcher
+
+```bash
+./launch.sh
+```
+
+Use menu option 1 (Docker stack) or option 2 (Native host processes). The launcher now attempts to auto-open the desktop GUI when the runtime supports display output.
+
+### B) Docker Full Stack
 
 ### 1. Start All Services
 
@@ -27,6 +37,12 @@ docker compose up -d
 docker ps
 ```
 
+Optional: skip container desktop GUI service when running from raw compose.
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
 **Expected Output:**
 ```
 CONTAINER ID   IMAGE                        STATUS           PORTS
@@ -47,6 +63,21 @@ curl http://localhost:8004/health
 # {"status":"healthy","service":"...","timestamp":"2026-06-24T..."}
 ```
 
+### C) Devcontainer
+
+```bash
+# In VS Code:
+# Dev Containers: Rebuild and Reopen in Container
+
+bash .devcontainer/post_create.sh
+```
+
+Fast smoke setup without expensive rebuild steps:
+
+```bash
+MOHAWK_SKIP_LIBOQS_BUILD=1 MOHAWK_SKIP_PY_DEPS=1 bash .devcontainer/post_create.sh
+```
+
 ### 3. List Available Models
 
 ```bash
@@ -179,6 +210,23 @@ python test_user_functions.py
 # SUMMARY: 33/33 passed (100.0%)
 ```
 
+### Validate Model Select + Chat Inference Only
+
+```bash
+# List models
+curl http://localhost:8003/api/models
+
+# Load model
+curl -X POST http://localhost:8003/api/models/load \
+  -H "Content-Type: application/json" \
+  -d '{"model": "Llama-3-8B-Instruct-Q4_K_M"}'
+
+# Run chat inference
+curl -X POST http://localhost:8003/api/inference/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Hello from smoke test","temperature":0.7,"top_p":0.9,"max_tokens":128}'
+```
+
 ### View Logs
 
 ```bash
diff --git a/README.md b/README.md
index d85a18d..14fafac 100644
--- a/README.md
+++ b/README.md
@@ -71,36 +71,51 @@ A secure, scalable GUI for managing multi-device inference sessions with **enter
 
 ## 📦 Quick Start
 
-### Installation (3 minutes)
+### Option A: One-Click Launcher (Recommended)
 
 ```bash
-# Clone repository
-cd C:\Users\rwill\Mohawk-Inference-Engine
+./launch.sh
+```
+
+This bootstraps a local virtual environment, installs missing dependencies, and opens the interactive launcher for native or Docker full-stack modes.
+
+### Option B: Docker Full Stack
+
+```bash
+docker compose up -d --build
+```
 
-# Create virtual environment
-python -m venv venv
-venv\Scripts\activate  # Windows: venv\Scripts\activate
+Services:
+- GUI backend: `http://localhost:8003`
+- Worker service: `http://localhost:8004`
 
-# Install dependencies
+Desktop GUI auto-launches when the display environment supports it. To skip container desktop GUI launch:
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
+### Option C: Native API + Desktop GUI
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
 pip install -r requirements.txt
 
-# Generate auth key (first run only)
-mkdir -p certs
-python mohawk_gui/main.py --key-file certs/auth_key.pem
+# Start full stack from launcher
+python launch.py
 ```
 
-### Running the Dashboard
+### Validate Inference + Model Selection End-to-End
 
 ```bash
-# Development mode
-python mohawk_gui/main.py
-
-# Production mode with SSL
-python mohawk_gui/main.py \
-    --host 0.0.0.0 \
-    --port 8003 \
-    --ssl-enabled \
-    --key-file certs/auth_key.pem
+python test_user_functions.py
+```
+
+Expected summary:
+
+```text
+SUMMARY: 33/33 passed (100.0%)
 ```
 
 ### Building Executable (Windows)
@@ -266,8 +281,12 @@ docker run -d \
 
 ## 📚 Documentation
 
+- **[📦 Install Guide](INSTALL.md)** - prerequisites and environment setup
+- **[🛠️ Setup Guide](SETUP.md)** - local, Docker, and devcontainer run paths
 - **[📖 Dashboard Features Guide](mohawk_gui/DASHBOARD_FEATURES.md)** - Complete feature documentation
 - **[⚡ Quick Start Guide](mohawk_gui/QUICK_START.md)** - 3-minute setup guide
+- **[⚡ API Quick Start](QUICKSTART.md)** - endpoint-focused smoke flow
+- **[🐳 Docker Setup](DOCKER_SETUP.md)** - container runtime details and troubleshooting
 - **[🏗️ Implementation Plan](GUI_IMPLEMENTATION_PLAN.md)** - Architecture details
 - **[✅ Production Readiness](GUI_PRODUCTION_READINESS.md)** - Quality checklist
 
diff --git a/SETUP.md b/SETUP.md
new file mode 100644
index 0000000..16c9e8d
--- /dev/null
+++ b/SETUP.md
@@ -0,0 +1,76 @@
+# Mohawk Inference Engine - Setup Guide
+
+## Setup Options
+
+## 1) One-Click Launcher (recommended)
+
+```bash
+./launch.sh
+```
+
+What it does:
+- Creates/uses local virtual environment
+- Installs missing dependencies
+- Offers native and Docker full-stack launch modes
+- Auto-launches desktop GUI when environment supports it
+
+## 2) Docker Full Stack
+
+```bash
+docker compose up -d --build
+```
+
+Services:
+- GUI backend: `http://localhost:8003`
+- Worker: `http://localhost:8004`
+
+Desktop GUI container behavior:
+- Starts when display is available
+- Exits cleanly if `DISPLAY` is missing
+
+Skip desktop GUI container explicitly:
+
+```bash
+MOHAWK_SKIP_DESKTOP_GUI=1 docker compose up -d --build
+```
+
+## 3) Native Backend + GUI
+
+```bash
+source .venv/bin/activate
+python launch.py
+```
+
+Or run API services manually:
+
+```bash
+python -m uvicorn prototype.worker:app --host 127.0.0.1 --port 8004
+python -m uvicorn prototype.gui_backend:app --host 127.0.0.1 --port 8003
+```
+
+## Health Checks
+
+```bash
+curl http://localhost:8003/health
+curl http://localhost:8004/health
+```
+
+## Functional Validation
+
+Run end-to-end checks for model selection and chat inference:
+
+```bash
+python test_user_functions.py
+```
+
+Expected summary:
+
+```text
+SUMMARY: 33/33 passed (100.0%)
+```
+
+## Troubleshooting
+
+- If GUI does not open in Docker mode, verify `DISPLAY` and X11 access.
+- If ports are busy (`8003`, `8004`), stop conflicting processes before launch.
+- If `docker` is unavailable in devcontainer, rebuild container to apply `.devcontainer/devcontainer.json` features.