Skip to content

FAQ.md

Latest commit

 

History

History
103 lines (71 loc) · 5.9 KB

FAQ.md

File metadata and controls

103 lines (71 loc) · 5.9 KB
Raw

❓ Frequently Asked Questions (FAQ) & Troubleshooting

Comprehensive answers to common questions about hardware compatibility, performance tuning, model weights, and troubleshooting (mirrored from Ollama & LM Studio FAQ standards).

 Hardware & System Requirements

What Macs are supported?

DreamBees MLX Studio supports all Apple Silicon Macs:

  • Apple M1, M1 Pro, M1 Max, M1 Ultra
  • Apple M2, M2 Pro, M2 Max, M2 Ultra
  • Apple M3, M3 Pro, M3 Max
  • Apple M4, M4 Pro, M4 Max

Note: Intel-based Macs are not supported as MLX requires Apple Silicon Unified Memory Architecture (UMA).

How much RAM is required?

  • 8 GB Unified Memory: Runs Z-Image Turbo (6B), Sana 2.0 Sprint (~0.4s speed), and FLUX.2 Klein 4B.
  • 16 GB Unified Memory: Recommended for Z-Image Turbo (6B), FLUX.2 Klein (9B), Wan2.1, and Stable Diffusion 3.5 Turbo.
  • 32 GB+ Unified Memory: Supports simultaneous model caching and ultra studio resolution.

⚡ Performance & Optimization

Why does generation feel smooth without slowing down my Mac?

DreamBees MLX applies four system optimizations:

  1. Low Scheduling Priority (nice -n 10): Ensures macOS WindowServer and UI threads get 100% priority for 60 FPS mouse/desktop fluidity.
  2. Unified Memory Dynamic Memory Limit (25%–40% RAM max total, 64MB–256MB cache limit): Dynamic RAM ceiling auto-scales based on model parameter count (30% for 4B models, 40% for 6B/9B models like Z-Image Turbo / FLUX 9B), strictly reserving 60%–75% of RAM for macOS WindowServer to prevent Metal memory from starving the system using mx.set_memory_limit(), mx.set_cache_limit(), and an 75% system VRAM circuit breaker.
  3. Prompt Clause Deduplication (sanitizeAndDeduplicatePrompt): Eliminates redundant prompt clauses, code fences, and unclosed tags to keep text encoder matrices clean.
  4. Post-Encoding Weight Eviction: Automatically evicts T5 and CLIP text encoder weights immediately after prompt tokenization.

💬 Studio & Voice Dictation

How does Voice Dictation (⌘⇧V) work?

Press ⌘ + ⇧ + V (or Ctrl+Shift+V) anywhere in DreamBees Studio to toggle instant voice dictation. You can speak your prompt intent naturally in over 30 languages.

Issue: Microphone permission denied on macOS

  • Solution: Open macOS System Settings > Privacy & Security > Microphone, and ensure DreamBees MLX Studio is toggled ON. Alternatively, click Grant Microphone Permission inside the Voice Dictation capsule bar in the app.

🥦 BroccoliDB Substrate & Enterprise Governance

What is BroccoliDB and how does it protect agent sessions?

BroccoliDB (broccolidb/) is a high-performance operational substrate that governs agent execution contexts, workspace state graphs (AgentContext, OrchestrationRuntime), and 4-pillar forensic health audit probes (checkSubstrateHealth). It ensures all prompt rewrite decisions, execution traces, and model sessions are durably checkpointed with zero data loss.

🤖 MCP Server & AI Agent Integration

How do I connect Claude Desktop or Cursor?

Add the following snippet to your claude_desktop_config.json or mcp_config.json:

{
  "mcpServers": {
    "dreambees-mlx": {
      "command": "node",
      "args": [
        "/Users/bozoegg/Downloads/DreamBeesMLX-main/mcp_server/dist/index.js"
      ]
    }
  }
}

💾 Storage & Memory Leak Management

How does DreamBees prevent database bloat and disk erosion?

DreamBees MLX includes an Anti-Disk Erosion Persistence Engine:

  1. Base64 Image Externalization: Generated base64 images are automatically saved as PNG files under userData/generations/, keeping SQLite rows lightweight (~200 bytes).
  2. 2 GB LRU Byte-Quota Engine: Disk cache is capped under a strict 2 GB budget. When usage exceeds 2 GB, oldest LRU files are evicted until usage drops to 80% quota (1.6 GB).
  3. Atomic File Swapping: Image files are written to .tmp.png files first before performing an atomic os.replace to eliminate corrupt or 0-byte image reads.
  4. 1-Click Storage Control: Users can optimize database space and purge image cache in Settings & Storage (src/pages/UserProfile.tsx).

🔧 Troubleshooting Common Issues

Issue: "Missing MLX dependencies" error on launch

  • Solution: DreamBees MLX includes a Touchless Environment Auto-Resolver (electron/environment_resolver.ts). Click Touchless Onboarding in the sidebar to trigger 1-click self-repair.

Issue: "Python 3 or pip not found"

  • Solution: The Touchless Resolver automatically invokes ensurepip and constructs an isolated virtual environment at ~/Library/Application Support/DreamBees Lite/python_env/.

🔒 Multi-Agent Safety & VRAM Circuit Breaker Q&A

How does the 75% VRAM Circuit Breaker work?

If active Metal GPU memory reaches 75% of your Mac's hardware memory ceiling during inference, the Python daemon's IPCStepwiseHandler instantly triggers a circuit breaker. It halts sampling cleanly (RuntimeError), unloads unneeded weights, flushes Metal caches via mx.clear_cache(), and returns a safe error payload to Electron—guaranteeing 0% risk of system UI stutters or macOS freezes.

How are concurrent requests handled when multiple AI Agents submit prompts?

The sidecar daemon manages incoming requests via a thread-safe task_queue worker thread (threading.Thread(target=task_worker)). Requests are serialized sequentially so that only one model card is loaded into Unified Memory at a time, eliminating VRAM contention and GPU allocation spikes.

Does TAESD live previewing consume extra GPU memory?

No. Intermediate previews use sub-sampled TAESD neural latent decoders (taesd_fast_latent_decode) operating on small 192x192 JPEG thumbnails. Because it reads directly from existing latent Metal arrays without executing full VAE decodes, previewing incurs 0% extra VAE VRAM overhead.