Quick Start

Get HeadlessX running, download the required models, create an API key, and make your first operator requests.

by @saifyxpro

HeadlessX Quick Start

Prerequisites

For the main HeadlessX workspace, the recommended local baseline is:

  • Node.js 22
  • pnpm 9 or newer
  • PostgreSQL
  • Redis
  • Python 3.10 or newer for yt-engine
  • Docker if you prefer containerized infrastructure

1. Clone and install

2. Create your environment file

Minimum local values:

Local mode still needs infrastructure

If you do not run the full platform in Docker, PostgreSQL and Redis still need to be available somewhere. Queue-backed website crawl also requires the worker process, which is started for you by pnpm dev.

Generate secure values for:

Use them for:

  • DASHBOARD_INTERNAL_API_KEY
  • CREDENTIAL_ENCRYPTION_KEY

3. Download the CAPTCHA models

Alternative commands also work:

4. Prepare the workspace

5. Start the stack

Recommended for development:

That starts:

  • API
  • queue worker
  • web dashboard
  • HTML-to-Markdown service
  • yt-engine

If you prefer a one-command container setup, see Docker Setup. Full Docker now includes yt-engine in the compose stack.

6. Create an API key

Open the dashboard at http://localhost:3000, go to the API keys page, and create a key. Use that key for all external HTTP and MCP clients.

7. Optional: install the CLI

8. Make your first requests

Website HTML:

Google AI Search:

CLI example:

9. Set up MCP

If you want to use HeadlessX from an MCP client, continue with MCP Setup.

Related Docs

CLI

Install the published CLI and run the same operator API from the terminal.

Environment Variables

Review the required runtime variables for local, mixed, and self-hosted deployments.

Next Steps

MCP Setup

Connect HeadlessX to remote MCP clients and configure API key authentication.

Agent Skills

Install the HeadlessX skill into supported AI coding agents.