Add VNC console bridge and expose API

Author: msinhore

README.md

@@ -215,6 +215,12 @@ sudo systemctl restart firecracker-cloudstack-agent.service
 - Each VM runs inside a detached tmux session named `fc-<vm_name>`; list active sessions with `tmux ls`.
 - Attach to the microVM console using `tmux attach -t fc-<vm_name>` and detach without stopping it via `Ctrl-b d`.
 - If a session is missing, the agent recreates it when the VM boots; use `tmux kill-session -t fc-<vm_name>` only for advanced troubleshooting.
+
+### VNC Console Bridge
+- `POST /v1/vms/{name}/console` spawns an `Xvfb` + `xterm` + `x11vnc` bridge bound to the VM's tmux session and returns `{host, port, password}` ready for the CloudStack console proxy. `DELETE /v1/vms/{name}/console` tears it down.
+- The CLI helper now supports `firecracker.py console <payload.json>` to fetch the same tuple programmatically.
+- Runtime assets live under `/var/run/firecracker/vnc/` (state JSON, password files). Adjust `defaults.console` in the agent config to tune port ranges, bind address, window geometry, fonts, or read-only mode.
+- Ensure the host has `x11vnc`, `xterm`, and `xvfb` installed; the Debian packaging pulls these dependencies.
 ---
 ## CloudStack Integration
 1. **Install extension on the management server**:

firecracker.py

@@ -362,6 +362,12 @@ def op_recover(ctx):
     data = _json_or_fail(_req("POST", url, ctx.agent, json_body=payload))
     _ok(data)
 
+def op_console(ctx):
+    """POST /v1/vms/{name}/console — obtain VNC bridge connection info."""
+    url = f"{ctx.agent.base_url}/vms/{ctx.vm_name}/console"
+    data = _json_or_fail(_req("POST", url, ctx.agent))
+    _ok(data)
+
 # -------------------------- main --------------------------
 def main():
     """Parse CLI, build context, dispatch operation over HTTP."""
@@ -382,6 +388,7 @@ def main():
         "status": op_status,
         "state": op_status,
         "recover": op_recover,
+        "console": op_console,
     }
 
     if operation not in ops:

host-agent/api/handlers.py

@@ -23,6 +23,7 @@
 from state import StateManager
 from utils.filesystem import paths
 from utils.validation import validate_name
+from utils.vnc_console import VNCConsoleManager
 
 logger = logging.getLogger("fc-agent")
 
@@ -36,6 +37,7 @@ def __init__(self, agent_defaults: Dict[str, Any], ui_config: Optional[Dict[str,
         self.vm_lifecycle = VMLifecycle(agent_defaults)
         self.config_manager = ConfigManager(agent_defaults)
         self.state_manager = StateManager(agent_defaults)
+        self.vnc_console = VNCConsoleManager(agent_defaults)
 
     def v1_ui_config(self) -> Dict[str, Any]:
         cfg = self.ui_config or {}
@@ -471,6 +473,40 @@ def v1_vm_reboot_by_name(self, vm_name: str) -> Dict[str, Any]:
             logger.exception("Reboot VM failed: %s", e)
             raise HTTPException(status_code=500, detail=f"Reboot VM failed: {e}")
 
+    def v1_vm_console_start(self, vm_name: str) -> Dict[str, Any]:
+        """Start (or reuse) the VNC bridge for a VM console."""
+        try:
+            info = self.vnc_console.ensure_console(vm_name)
+            return {
+                "status": "success",
+                "message": f"VNC console ready for VM {vm_name}",
+                "vm_name": vm_name,
+                "host": info.get("host"),
+                "port": info.get("port"),
+                "password": info.get("password"),
+                "created_at": info.get("created_at"),
+            }
+        except RuntimeError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.exception("Failed to start VNC console for VM %s: %s", vm_name, exc)
+            raise HTTPException(status_code=500, detail=f"Failed to start VNC console: {exc}")
+
+    def v1_vm_console_stop(self, vm_name: str) -> Dict[str, Any]:
+        """Stop the VNC bridge for a VM console."""
+        try:
+            info = self.vnc_console.stop_console(vm_name)
+            if isinstance(info, dict) and "vm_name" not in info:
+                info["vm_name"] = vm_name
+            return info
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.exception("Failed to stop VNC console for VM %s: %s", vm_name, exc)
+            raise HTTPException(status_code=500, detail=f"Failed to stop VNC console: {exc}")
+
     def v1_vm_start_by_name(self, vm_name: str, req: SpecRequest) -> Dict[str, Any]:
         """Start VM by name (uses existing config on disk)."""
         try:
@@ -504,6 +540,7 @@ def v1_index(self) -> Dict[str, Any]:
                 "/v1/vms/{name}/start",
                 "/v1/vms/{name}/stop",
                 "/v1/vms/{name}/reboot",
+                "/v1/vms/{name}/console",
                 "/v1/vms/{name}",
                 "/v1/vms/{name}/recover",
                 "/v1/vms/{name}/status",

host-agent/api/routes.py

@@ -86,6 +86,14 @@ def v1_vm_reboot_by_name(vm_name: str):
     def v1_vm_recover_by_name(vm_name: str, req: Optional[SpecRequest] = None):
         return handlers.v1_vm_recover_by_name(vm_name, req)
 
+    @app.post("/v1/vms/{vm_name}/console", **protected)
+    def v1_vm_console_start(vm_name: str):
+        return handlers.v1_vm_console_start(vm_name)
+
+    @app.delete("/v1/vms/{vm_name}/console", **protected)
+    def v1_vm_console_stop(vm_name: str):
+        return handlers.v1_vm_console_stop(vm_name)
+
     # System management endpoints
     @app.post("/v1/graceful-shutdown", **protected)
     def v1_graceful_shutdown():

host-agent/debian/changelog

@@ -1,3 +1,14 @@
+firecracker-cloudstack-agent (0.4.0-1) unstable; urgency=medium
+
+  * Add a VNC console bridge leveraging Xvfb/xterm/x11vnc and expose it via
+    the new `/v1/vms/{name}/console` API endpoints.
+  * Extend the firecracker.py client with a `console` action and update the
+    documentation with instructions for integrating the console proxy.
+  * Ship the new console manager module in the Debian package and pull in the
+    required x11vnc/xterm/xvfb packages as dependencies.
+
+ -- Marco Sinhoreli <msinhore@gmail.com>  Fri, 17 Oct 2025 10:15:00 +0000
+
 firecracker-cloudstack-agent (0.3.2-1) unstable; urgency=medium
 
   * Fix VM provisioning to honor `maxRam` from CloudStack payloads when

host-agent/debian/control

@@ -8,7 +8,7 @@ Build-Depends: debhelper-compat (= 13), nodejs, npm
 
 Package: firecracker-cloudstack-agent
 Architecture: all
-Depends: ${misc:Depends}, jq, curl, iproute2, bridge-utils, tmux, openssl, python3-pamela, python3-uvicorn, python3-psutil, python3-fastapi, python3-libtmux, python3-pyroute2, python3-typer, python3-openvswitch, python3-ovsdbapp
+Depends: ${misc:Depends}, jq, curl, iproute2, bridge-utils, tmux, openssl, python3-pamela, python3-uvicorn, python3-psutil, python3-fastapi, python3-libtmux, python3-pyroute2, python3-typer, python3-openvswitch, python3-ovsdbapp, x11vnc, xterm, xvfb
 Recommends: openvswitch-switch
 Description: Firecracker agent with pluggable storage and networking backends for CloudStack
  A local HTTP API/CLI to manage Firecracker microVMs with file/LVM/LVM-thin storage backends

host-agent/debian/firecracker-agent.json

@@ -18,6 +18,15 @@
     "net": {
       "driver": "linux-bridge-vlan",
       "host_bridge": "cloudbr1"
+    },
+    "console": {
+      "bind_host": "0.0.0.0",
+      "port_min": 5900,
+      "port_max": 5999,
+      "geometry": "1024x768x24",
+      "xterm_geometry": "132x44",
+      "font_family": "Monospace",
+      "font_size": 14
     }
   },
   "security": {

host-agent/debian/install

@@ -24,6 +24,7 @@ host-agent/utils/auth.py                            usr/lib/firecracker-cloudsta
 host-agent/utils/validation.py                      usr/lib/firecracker-cloudstack-agent/utils/
 host-agent/utils/filesystem.py                      usr/lib/firecracker-cloudstack-agent/utils/
 host-agent/utils/tmux.py                            usr/lib/firecracker-cloudstack-agent/utils/
+host-agent/utils/vnc_console.py                     usr/lib/firecracker-cloudstack-agent/utils/
 host-agent/tools/fc_shutdown_service.py             usr/lib/firecracker-cloudstack-agent/tools/
 host-agent/api/__init__.py                          usr/lib/firecracker-cloudstack-agent/api/
 host-agent/api/handlers.py                          usr/lib/firecracker-cloudstack-agent/api/