Before You Submit
Target Area
infra/docker
Feature Category
Docker or deployment
Summary
Add first-class embedded VNC and noVNC support to Docker deployments so HeadlessX can expose its managed browser session from inside the API container. This would let operators complete interactive browser steps on remote VPS or server environments without needing a local desktop session.
Problem To Solve
Some HeadlessX workflows require a real interactive browser session, especially during first-run authentication, cookie bootstrap, CAPTCHA solving, and production debugging. In local development this can be handled with a native display, but Docker and VPS deployments usually run headless.
For an operators platform, interactive browser recovery and debugging should be available as a built-in deployment capability.
Proposed Solution
Add an optional embedded display and VNC stack to the Docker deployment path.
The Docker-based API service should be able to:
- start a managed virtual display when no real display is available
- expose that display through an embedded VNC server
- provide browser access through a noVNC web client for remote use
- make the feature configurable through environment variables
- default to a secure setup with password protection enabled
- allow an explicit opt-out for trusted local-only debugging
- document the required ports, environment variables, and recommended reverse proxy setup
From an operator point of view, the workflow should be simple:
- enable the feature in the Docker env file
- open the published noVNC URL
- authenticate with the configured VNC password
- complete the browser interaction once
- stop or keep the remote session available for future debugging
This should integrate cleanly with existing Docker and self-hosted flows, especially for browser-based bootstrap and troubleshooting tasks.
Alternatives Or Workarounds
None
Use Cases
- Complete Google or CAPTCHA-related bootstrap flows on a remote VPS without a physical display.
- Debug browser automation issues in Docker when a site behaves differently in production than in local development.
- Let self-hosted operators inspect the live browser state during authentication, cookie refresh, or anti-bot challenges.
- Support remote demos, onboarding, and troubleshooting without requiring additional desktop infrastructure.
- Keep Docker deployments fully self-contained for browser-based operator workflows.
Priority
High
Contribution
Before You Submit
Target Area
infra/docker
Feature Category
Docker or deployment
Summary
Add first-class embedded VNC and noVNC support to Docker deployments so HeadlessX can expose its managed browser session from inside the API container. This would let operators complete interactive browser steps on remote VPS or server environments without needing a local desktop session.
Problem To Solve
Some HeadlessX workflows require a real interactive browser session, especially during first-run authentication, cookie bootstrap, CAPTCHA solving, and production debugging. In local development this can be handled with a native display, but Docker and VPS deployments usually run headless.
For an operators platform, interactive browser recovery and debugging should be available as a built-in deployment capability.
Proposed Solution
Add an optional embedded display and VNC stack to the Docker deployment path.
The Docker-based API service should be able to:
From an operator point of view, the workflow should be simple:
This should integrate cleanly with existing Docker and self-hosted flows, especially for browser-based bootstrap and troubleshooting tasks.
Alternatives Or Workarounds
None
Use Cases
Priority
High
Contribution