Quick Start
Get HeadlessX running quickly with the published CLI, create an API key, and make your first operator requests.
by @saifyxpro
Fastest path
The fastest current setup path is the published CLI.
For most operators, this is enough:
That bootstraps HeadlessX into ~/.headlessx, writes the current runtime env files, and brings the full self-host stack up on the uncommon local defaults:
- dashboard:
http://localhost:34872 - API:
http://localhost:38473 - postgres:
35432 - redis:
36379 - html-to-md:
38081 - yt-engine:
38090
Prerequisites
CLI-managed self-host or production
- Node.js 22+
- Git
- Docker with Compose v2
Developer mode from source
- Node.js 22+
- Corepack with
pnpm@10.32.1 - Git
- Docker if you want infrastructure in containers
If your machine does not already use the pinned pnpm release:
1. Pick a mode
HeadlessX supports three CLI-managed modes:
| Mode | Best for | Result |
|---|---|---|
developer | contributors and direct repo development | clones the repo into ~/.headlessx/repo and prepares the source workspace |
self-host | local Docker runtime or a VPS on localhost ports | starts the full stack behind rare local ports |
production | domain-based deployment | starts the Docker app stack plus the Caddy/domain layer |
Common examples:
2. Open the dashboard and create an API key
For self-host, open:
Then go to the API keys screen and create a normal API key.
Use that key for:
- external HTTP clients
- the published CLI login flow
- MCP clients
Do not use DASHBOARD_INTERNAL_API_KEY in external clients.
3. Optional: log in with the CLI
Interactive:
Direct:
4. First Google AI Search run
Google AI Search now requires a one-time cookie bootstrap on the shared persistent browser profile.
- open
/playground/operators/google/ai-search - click
Build Cookies - browse Google normally and solve any one-time challenge
- click
Stop Browser
After that, the shared profile is reused for later Google searches.
Docker and VPS installs keep the shared browser profile in the browser_profile volume. Local source runs keep it under apps/api/data/browser-profile/default. That runtime profile data is not tracked in git.
5. Make your first requests
Website HTML:
Google AI Search:
CLI example:
6. Update an existing install
For existing self-host or production installs:
headlessx init update pulls the saved branch and reconciles missing env keys for the current mode. headlessx restart rebuilds Docker for self-host and production.
7. Developer mode from source
If you want the repo directly for development:
That is the preferred source-setup path now. It is more reliable than retyping the full repository bootstrap manually.
If you still prefer a direct source checkout workflow, keep these runtime values aligned with the current defaults:
8. Set up MCP
If you want to use HeadlessX from an MCP client, continue with MCP Setup.