Overview
Understand the runtime modes, required services, and deployment shape.
by @saifyxpro
HeadlessX can run in three practical ways:
| Mode | Best for | Notes |
|---|---|---|
| Mixed local | day-to-day development | run apps locally, keep infrastructure in Docker or Supabase |
| Full Docker | repeatable self-hosted deploys | good for operational consistency and now includes yt-engine |
| Fully local | advanced operators | requires local PostgreSQL and Redis installs |
Core services
| Service | Required | Why it exists |
|---|---|---|
| PostgreSQL | yes | state for API keys, settings, logs, proxies, and persisted data |
| Redis | required for queues | crawl and BullMQ-backed jobs |
| API | yes | /api/* and /mcp |
| Worker | required for queue jobs | processes crawl and background work |
| Web | optional for API-only usage | operator dashboard and playground |
| HTML-to-Markdown | recommended | better content extraction pipeline |
| yt-engine | required for YouTube features | metadata extraction and temporary save jobs |
Recommended setup order
- mixed local for development
- full Docker for reproducible runtime
- fully local only if you already manage PostgreSQL and Redis on the host OS
Important operational notes
- Website Crawl requires both Redis and the worker
- only
/api/operators/website/crawlneeds Redis in the website operator family - YouTube routes require
YT_ENGINE_URL - MCP uses normal API keys, not the dashboard internal key
pnpm devstarts the app-side services, but it does not install PostgreSQL or Redis for you