HeadlessX Files

HeadlessX v2.1.2

Released on March 25, 2026

HeadlessX v2.1.2 is the current CLI-first release for self-hosted operators, dashboard workflows, and agent-ready automation.

What's new

CLI-first setup and updates

• published lifecycle flow around headlessx init, start, stop, restart, status, doctor, logs, and init update
• modern interactive prompts with @clack/prompts
• improved health checks, loopback fallback, Docker log handling, and VPS operator UX
• workspace updates now reconcile missing env keys instead of only pulling the repo

Better self-hosting defaults

• rare default public host ports to avoid local conflicts:
• web 34872
• api 38473
• postgres 35432
• redis 36379
• html-to-md 38081
• yt-engine 38090
• new infra/domain-setup scaffold with Caddy for domain-based production deployment
• headlessx restart rebuilds Docker for self-host and production installs

Docker and browser runtime hardening

• fixed Docker startup issues around native dependencies and browser runtime boot
• switched API browser runtime to headfox-js
• stabilized browser release fetching for Linux Docker builds
• restored yt-engine in the full Docker stack
• web now waits for a healthy API before startup

Google AI Search improvements

• added shared-profile Google cookie bootstrap
• new Build Cookies and Stop Browser flow in the dashboard
• first Google run now requires one manual bootstrap session on the shared persistent profile
• improved structured errors and runtime setup messaging

Dashboard and operator UX

• improved operators catalog startup recovery
• clarified operator availability errors, especially for YouTube
• improved website crawl results with page overlay inspection
• hardened crawl SSE behavior and reconnect flow

Important changes

• older installs should update with:
• headlessx init update
• headlessx restart
• Google AI Search now requires a one-time cookie bootstrap before first real use
• full Docker includes yt-engine by default
• the tracked seeded browser profile has been removed; runtime profile data is now created and persisted on demand

Recommended update commands

Existing install on main

:::bash
npm install -g @headlessx-cli/core@latest
headlessx init update
headlessx restart
headlessx status
headlessx doctor