---
title: Docker Desktop Won't Start
summary: The most common first-run failure: HeartBeatAgents requires Docker Desktop running before it can launch any agent.
date: 2026-09-03
---

# Docker Desktop Won't Start

The most common first-run failure: HeartBeatAgents requires Docker Desktop running before it can launch any agent.

HeartBeatAgents uses Docker to isolate each agent's execution environment (see [Security](/en/docs/guides/security)): it's a hard requirement on every platform, not optional. If the app hangs on launch or agents fail to start, Docker not running is the most likely cause.

## Check Docker Desktop is actually running

Look for the Docker whale icon in your system tray (Windows) or menu bar (macOS). If it's missing, launch Docker Desktop manually and wait for it to report "Docker Desktop is running" before opening HeartBeatAgents again.

## Common causes

- **Virtualization not enabled**: on Windows, Docker Desktop requires WSL 2 or Hyper-V. Check Windows Features for "Virtual Machine Platform" and "Windows Subsystem for Linux."
- **Insufficient resources**: Docker Desktop's own settings (Preferences → Resources) cap how much CPU/RAM it can use. If it's set too low, containers can fail to start under load.
- **A previous Docker process didn't exit cleanly**: restart Docker Desktop fully (quit from the tray/menu bar icon, not just close the window) rather than relaunching over a stuck instance.

## Still stuck?

Check Docker Desktop's own diagnostic logs (Docker Desktop → Troubleshoot → Get support). Most launch failures are Docker-level, not HeartBeatAgents-level, and Docker's own diagnostics will usually name the exact cause.

## Related

- [Installation](/en/docs/getting-started/installation): the Docker Desktop prerequisite
- [System Requirements](/en/docs/getting-started/system-requirements): supported platforms and architectures