Fix devcontainer reliability and enable one-click full-stack desktop GUI launch

.devcontainer/Dockerfile

@@ -4,16 +4,18 @@ 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
 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 && \

.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"
 }

.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"

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

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

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.

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