Overview
Understand the current HeadlessX modes, required services, and deployment shape.
by @saifyxpro
HeadlessX currently exposes three CLI-managed modes:
| Mode | Best for | Notes |
|---|---|---|
developer | repo contributors and direct product development | clones the repo into ~/.headlessx/repo and prepares the source workspace |
self-host | local Docker runtime or a VPS on localhost ports | runs the full stack on rare host ports and is the recommended default |
production | domain-based deployment | runs the Docker app stack plus the infra/domain-setup Caddy layer |
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
self-hostfor the fastest repeatable local or VPS deploymentproductionwhen you are ready for custom domains and HTTPSdeveloperwhen you need the repo directly and want to extend HeadlessX itself
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, but CLIself-hostandproductionnow write it automatically - MCP uses normal API keys, not the dashboard internal key
- Google AI Search now requires a one-time
Build Cookiesrun on the shared persistent browser profile before the first search - container-internal ports stay stable for Docker networking, but host defaults now use the rarer public values
34872,38473,35432,36379,38081, and38090
Proxy recommendation
Self-hosting HeadlessX on a VPS does not change the fact that your outbound traffic still comes from datacenter IP ranges. If targets are sensitive to datacenter traffic, add residential or ISP proxy capacity instead of assuming the VPS network alone will be enough.