portacode 1.4.11.dev5__py3-none-any.whl → 1.4.12.dev3__py3-none-any.whl

portacode/connection/handlers/proxmox_infra.py

@@ -2,17 +2,20 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import os
+import secrets
 import shutil
 import stat
 import subprocess
 import sys
 import time
+import threading
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Optional, Tuple
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
 
 import platformdirs
 
@@ -38,6 +41,58 @@ DNS_SERVER = "1.1.1.1"
 IFACES_PATH = Path("/etc/network/interfaces")
 SYSCTL_PATH = Path("/etc/sysctl.d/99-portacode-forward.conf")
 UNIT_DIR = Path("/etc/systemd/system")
+_MANAGED_CONTAINERS_CACHE_TTL_S = 30.0
+_MANAGED_CONTAINERS_CACHE: Dict[str, Any] = {"timestamp": 0.0, "summary": None}
+_MANAGED_CONTAINERS_CACHE_LOCK = threading.Lock()
+
+ProgressCallback = Callable[[int, int, Dict[str, Any], str, Optional[Dict[str, Any]]], None]
+
+
+def _emit_progress_event(
+    handler: SyncHandler,
+    *,
+    step_index: int,
+    total_steps: int,
+    step_name: str,
+    step_label: str,
+    status: str,
+    message: str,
+    phase: str,
+    request_id: Optional[str],
+    details: Optional[Dict[str, Any]] = None,
+) -> None:
+    loop = handler.context.get("event_loop")
+    if not loop or loop.is_closed():
+        logger.debug(
+            "progress event skipped (no event loop) step=%s status=%s",
+            step_name,
+            status,
+        )
+        return
+
+    payload: Dict[str, Any] = {
+        "event": "proxmox_container_progress",
+        "step_name": step_name,
+        "step_label": step_label,
+        "status": status,
+        "phase": phase,
+        "step_index": step_index,
+        "total_steps": total_steps,
+        "message": message,
+    }
+    if request_id:
+        payload["request_id"] = request_id
+    if details:
+        payload["details"] = details
+
+    future = asyncio.run_coroutine_threadsafe(handler.send_response(payload), loop)
+    future.add_done_callback(
+        lambda fut: logger.warning(
+            "Failed to emit progress event for %s: %s", step_name, fut.exception()
+        )
+        if fut.exception()
+        else None
+    )
 
 
 def _call_subprocess(cmd: List[str], **kwargs: Any) -> subprocess.CompletedProcess[str]:
@@ -239,12 +294,185 @@ def _ensure_containers_dir() -> None:
     CONTAINERS_DIR.mkdir(parents=True, exist_ok=True)
 
 
+def _invalidate_managed_containers_cache() -> None:
+    with _MANAGED_CONTAINERS_CACHE_LOCK:
+        _MANAGED_CONTAINERS_CACHE["timestamp"] = 0.0
+        _MANAGED_CONTAINERS_CACHE["summary"] = None
+
+
+def _load_managed_container_records() -> List[Dict[str, Any]]:
+    _ensure_containers_dir()
+    records: List[Dict[str, Any]] = []
+    for path in sorted(CONTAINERS_DIR.glob("ct-*.json")):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except Exception as exc:  # pragma: no cover - best effort logging
+            logger.debug("Unable to read container record %s: %s", path, exc)
+            continue
+        records.append(payload)
+    return records
+
+
+def _build_managed_containers_summary(records: List[Dict[str, Any]]) -> Dict[str, Any]:
+    total_ram = 0
+    total_disk = 0
+    total_cpu_share = 0.0
+    containers: List[Dict[str, Any]] = []
+
+    def _as_int(value: Any) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return 0
+
+    def _as_float(value: Any) -> float:
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return 0.0
+
+    for record in sorted(records, key=lambda entry: _as_int(entry.get("vmid"))):
+        ram_mib = _as_int(record.get("ram_mib"))
+        disk_gib = _as_int(record.get("disk_gib"))
+        cpu_share = _as_float(record.get("cpus"))
+        total_ram += ram_mib
+        total_disk += disk_gib
+        total_cpu_share += cpu_share
+        status = (record.get("status") or "unknown").lower()
+        containers.append(
+            {
+                "vmid": str(_as_int(record.get("vmid"))) if record.get("vmid") is not None else None,
+                "hostname": record.get("hostname"),
+                "template": record.get("template"),
+                "storage": record.get("storage"),
+                "disk_gib": disk_gib,
+                "ram_mib": ram_mib,
+                "cpu_share": cpu_share,
+                "created_at": record.get("created_at"),
+                "status": status,
+            }
+        )
+
+    return {
+        "updated_at": datetime.utcnow().isoformat() + "Z",
+        "count": len(containers),
+        "total_ram_mib": total_ram,
+        "total_disk_gib": total_disk,
+        "total_cpu_share": round(total_cpu_share, 2),
+        "containers": containers,
+    }
+
+
+def _get_managed_containers_summary(force: bool = False) -> Dict[str, Any]:
+    def _refresh_container_statuses(records: List[Dict[str, Any]], config: Dict[str, Any] | None) -> None:
+        if not records or not config:
+            return
+        try:
+            proxmox = _connect_proxmox(config)
+            node = _get_node_from_config(config)
+            statuses = {
+                str(ct.get("vmid")): (ct.get("status") or "unknown").lower()
+                for ct in proxmox.nodes(node).lxc.get()
+            }
+        except Exception as exc:  # pragma: no cover - best effort
+            logger.debug("Failed to refresh container statuses: %s", exc)
+            return
+        for record in records:
+            vmid = record.get("vmid")
+            if vmid is None:
+                continue
+            try:
+                vmid_key = str(int(vmid))
+            except (ValueError, TypeError):
+                continue
+            status = statuses.get(vmid_key)
+            if status:
+                record["status"] = status
+
+    now = time.monotonic()
+    with _MANAGED_CONTAINERS_CACHE_LOCK:
+        cache_ts = _MANAGED_CONTAINERS_CACHE["timestamp"]
+        cached = _MANAGED_CONTAINERS_CACHE["summary"]
+    if not force and cached and now - cache_ts < _MANAGED_CONTAINERS_CACHE_TTL_S:
+        return cached
+    config = _load_config()
+    records = _load_managed_container_records()
+    _refresh_container_statuses(records, config)
+    summary = _build_managed_containers_summary(records)
+    with _MANAGED_CONTAINERS_CACHE_LOCK:
+        _MANAGED_CONTAINERS_CACHE["timestamp"] = now
+        _MANAGED_CONTAINERS_CACHE["summary"] = summary
+    return summary
+
+
 def _format_rootfs(storage: str, disk_gib: int, storage_type: str) -> str:
     if storage_type in ("lvm", "lvmthin"):
         return f"{storage}:{disk_gib}"
     return f"{storage}:{disk_gib}G"
 
 
+def _get_provisioning_user_info(message: Dict[str, Any]) -> Tuple[str, str, str]:
+    user = (message.get("username") or "svcuser").strip() if message else "svcuser"
+    user = user or "svcuser"
+    password = message.get("password")
+    if not password:
+        password = secrets.token_urlsafe(10)
+    ssh_key = (message.get("ssh_key") or "").strip() if message else ""
+    return user, password, ssh_key
+
+
+def _friendly_step_label(step_name: str) -> str:
+    if not step_name:
+        return "Step"
+    normalized = step_name.replace("_", " ").strip()
+    return normalized.capitalize()
+
+
+def _build_bootstrap_steps(user: str, password: str, ssh_key: str) -> List[Dict[str, Any]]:
+    steps = [
+        {
+            "name": "apt_update",
+            "cmd": "apt-get update -y",
+            "retries": 4,
+            "retry_delay_s": 5,
+            "retry_on": [
+                "Temporary failure resolving",
+                "Could not resolve",
+                "Failed to fetch",
+            ],
+        },
+        {
+            "name": "install_deps",
+            "cmd": "apt-get install -y python3 python3-pip sudo --fix-missing",
+            "retries": 5,
+            "retry_delay_s": 5,
+            "retry_on": [
+                "lock-frontend",
+                "Unable to acquire the dpkg frontend lock",
+                "Temporary failure resolving",
+                "Could not resolve",
+                "Failed to fetch",
+            ],
+        },
+        {"name": "user_exists", "cmd": f"id -u {user} >/dev/null 2>&1 || adduser --disabled-password --gecos '' {user}", "retries": 0},
+        {"name": "add_sudo", "cmd": f"usermod -aG sudo {user}", "retries": 0},
+    ]
+    if password:
+        steps.append({"name": "set_password", "cmd": f"echo '{user}:{password}' | chpasswd", "retries": 0})
+    if ssh_key:
+        steps.append({
+            "name": "add_ssh_key",
+            "cmd": f"install -d -m 700 /home/{user}/.ssh && echo '{ssh_key}' >> /home/{user}/.ssh/authorized_keys && chown -R {user}:{user} /home/{user}/.ssh",
+            "retries": 0,
+        })
+    steps.extend([
+        {"name": "pip_upgrade", "cmd": "python3 -m pip install --upgrade pip", "retries": 0},
+        {"name": "install_portacode", "cmd": "python3 -m pip install --upgrade portacode", "retries": 0},
+        {"name": "portacode_connect", "type": "portacode_connect", "timeout_s": 30},
+    ])
+    return steps
+
+
 def _get_storage_type(storages: Iterable[Dict[str, Any]], storage_name: str) -> str:
     for entry in storages:
         if entry.get("storage") == storage_name:
@@ -252,14 +480,14 @@ def _get_storage_type(storages: Iterable[Dict[str, Any]], storage_name: str) ->
     return ""
 
 
-def _validate_positive_int(value: Any, default: int) -> int:
+def _validate_positive_number(value: Any, default: float) -> float:
     try:
-        candidate = int(value)
+        candidate = float(value)
         if candidate > 0:
             return candidate
     except Exception:
         pass
-    return default
+    return float(default)
 
 
 def _wait_for_task(proxmox: Any, node: str, upid: str) -> Tuple[Dict[str, Any], float]:
@@ -311,10 +539,44 @@ def _start_container(proxmox: Any, node: str, vmid: int) -> Tuple[Dict[str, Any]
     return _wait_for_task(proxmox, node, upid)
 
 
+def _stop_container(proxmox: Any, node: str, vmid: int) -> Tuple[Dict[str, Any], float]:
+    status = proxmox.nodes(node).lxc(vmid).status.current.get()
+    if status.get("status") != "running":
+        return status, 0.0
+    upid = proxmox.nodes(node).lxc(vmid).status.stop.post()
+    return _wait_for_task(proxmox, node, upid)
+
+
+def _delete_container(proxmox: Any, node: str, vmid: int) -> Tuple[Dict[str, Any], float]:
+    upid = proxmox.nodes(node).lxc(vmid).delete()
+    return _wait_for_task(proxmox, node, upid)
+
+
 def _write_container_record(vmid: int, payload: Dict[str, Any]) -> None:
     _ensure_containers_dir()
     path = CONTAINERS_DIR / f"ct-{vmid}.json"
     path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    _invalidate_managed_containers_cache()
+
+
+def _read_container_record(vmid: int) -> Dict[str, Any]:
+    path = CONTAINERS_DIR / f"ct-{vmid}.json"
+    if not path.exists():
+        raise FileNotFoundError(f"Container record {path} missing")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _update_container_record(vmid: int, updates: Dict[str, Any]) -> None:
+    record = _read_container_record(vmid)
+    record.update(updates)
+    _write_container_record(vmid, record)
+
+
+def _remove_container_record(vmid: int) -> None:
+    path = CONTAINERS_DIR / f"ct-{vmid}.json"
+    if path.exists():
+        path.unlink()
+        _invalidate_managed_containers_cache()
 
 
 def _build_container_payload(message: Dict[str, Any], config: Dict[str, Any]) -> Dict[str, Any]:
@@ -326,16 +588,14 @@ def _build_container_payload(message: Dict[str, Any], config: Dict[str, Any]) ->
 
     bridge = config.get("network", {}).get("bridge", DEFAULT_BRIDGE)
     hostname = (message.get("hostname") or "").strip()
-    disk_gib = _validate_positive_int(message.get("disk_gib") or message.get("disk"), 32)
-    ram_mib = _validate_positive_int(message.get("ram_mib") or message.get("ram"), 2048)
-    cpus = _validate_positive_int(message.get("cpus"), 1)
+    disk_gib = int(max(round(_validate_positive_number(message.get("disk_gib") or message.get("disk"), 3)), 1))
+    ram_mib = int(max(round(_validate_positive_number(message.get("ram_mib") or message.get("ram"), 2048)), 1))
+    cpus = _validate_positive_number(message.get("cpus"), 0.2)
     storage = message.get("storage") or config.get("default_storage") or ""
     if not storage:
         raise ValueError("Storage pool could not be determined.")
 
-    user = (message.get("username") or "svcuser").strip() or "svcuser"
-    password = message.get("password") or ""
-    ssh_key = (message.get("ssh_key") or "").strip()
+    user, password, ssh_key = _get_provisioning_user_info(message)
 
     payload = {
         "template": template,
@@ -355,6 +615,38 @@ def _build_container_payload(message: Dict[str, Any], config: Dict[str, Any]) ->
     return payload
 
 
+def _ensure_infra_configured() -> Dict[str, Any]:
+    config = _load_config()
+    if not config or not config.get("token_value"):
+        raise RuntimeError("Proxmox infrastructure is not configured.")
+    return config
+
+
+def _get_node_from_config(config: Dict[str, Any]) -> str:
+    return config.get("node") or DEFAULT_NODE_NAME
+
+
+def _parse_ctid(message: Dict[str, Any]) -> int:
+    for key in ("ctid", "vmid"):
+        value = message.get(key)
+        if value is not None:
+            try:
+                return int(str(value).strip())
+            except ValueError:
+                raise ValueError(f"{key} must be an integer") from None
+    raise ValueError("ctid is required")
+
+
+def _ensure_container_managed(
+    proxmox: Any, node: str, vmid: int
+) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    record = _read_container_record(vmid)
+    ct_cfg = proxmox.nodes(node).lxc(str(vmid)).config.get()
+    if not ct_cfg or MANAGED_MARKER not in (ct_cfg.get("description") or ""):
+        raise RuntimeError(f"Container {vmid} is not managed by Portacode.")
+    return record, ct_cfg
+
+
 def _connect_proxmox(config: Dict[str, Any]) -> Any:
     ProxmoxAPI = _ensure_proxmoxer()
     return ProxmoxAPI(
@@ -367,10 +659,10 @@ def _connect_proxmox(config: Dict[str, Any]) -> Any:
     )
 
 
-def _run_pct(vmid: int, cmd: str) -> Dict[str, Any]:
+def _run_pct(vmid: int, cmd: str, input_text: Optional[str] = None) -> Dict[str, Any]:
     full = ["pct", "exec", str(vmid), "--", "bash", "-lc", cmd]
     start = time.time()
-    proc = subprocess.run(full, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    proc = subprocess.run(full, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, input=input_text)
     return {
         "cmd": cmd,
         "returncode": proc.returncode,
@@ -471,18 +763,36 @@ def _summarize_error(res: Dict[str, Any]) -> str:
     return "Command failed; see stdout/stderr for details."
 
 
-def _run_setup_steps(vmid: int, steps: List[Dict[str, Any]], user: str) -> Tuple[List[Dict[str, Any]], bool]:
+def _run_setup_steps(
+    vmid: int,
+    steps: List[Dict[str, Any]],
+    user: str,
+    progress_callback: Optional[ProgressCallback] = None,
+    start_index: int = 1,
+    total_steps: Optional[int] = None,
+) -> Tuple[List[Dict[str, Any]], bool]:
     results: List[Dict[str, Any]] = []
-    for step in steps:
+    computed_total = total_steps if total_steps is not None else start_index + len(steps) - 1
+    for offset, step in enumerate(steps):
+        step_index = start_index + offset
+        if progress_callback:
+            progress_callback(step_index, computed_total, step, "in_progress", None)
+
         if step.get("type") == "portacode_connect":
             res = _portacode_connect_and_read_key(vmid, user, timeout_s=step.get("timeout_s", 10))
             res["name"] = step["name"]
             results.append(res)
             if not res.get("ok"):
+                if progress_callback:
+                    progress_callback(step_index, computed_total, step, "failed", res)
                 return results, False
+            if progress_callback:
+                progress_callback(step_index, computed_total, step, "completed", res)
             continue
 
         attempts = 0
+        retry_on = step.get("retry_on", [])
+        max_attempts = step.get("retries", 0) + 1
         while True:
             attempts += 1
             res = _run_pct(vmid, step["cmd"])
@@ -492,61 +802,47 @@ def _run_setup_steps(vmid: int, steps: List[Dict[str, Any]], user: str) -> Tuple
                 res["error_summary"] = _summarize_error(res)
             results.append(res)
             if res["returncode"] == 0:
+                if progress_callback:
+                    progress_callback(step_index, computed_total, step, "completed", res)
                 break
-            retry_on = step.get("retry_on", [])
-            if attempts >= step.get("retries", 0) + 1:
-                return results, False
-            if any(tok in (res.get("stderr", "") + res.get("stdout", "")) for tok in retry_on):
+
+            will_retry = False
+            if attempts < max_attempts and retry_on:
+                stderr_stdout = (res.get("stderr", "") + res.get("stdout", ""))
+                if any(tok in stderr_stdout for tok in retry_on):
+                    will_retry = True
+
+            if progress_callback:
+                status = "retrying" if will_retry else "failed"
+                progress_callback(step_index, computed_total, step, status, res)
+
+            if will_retry:
                 time.sleep(step.get("retry_delay_s", 3))
                 continue
+
             return results, False
     return results, True
 
 
-def _bootstrap_portacode(vmid: int, user: str, password: str, ssh_key: str) -> Tuple[str, List[Dict[str, Any]]]:
-    steps = [
-        {
-            "name": "apt_update",
-            "cmd": "apt-get update -y",
-            "retries": 4,
-            "retry_delay_s": 5,
-            "retry_on": [
-                "Temporary failure resolving",
-                "Could not resolve",
-                "Failed to fetch",
-            ],
-        },
-        {
-            "name": "install_deps",
-            "cmd": "apt-get install -y python3 python3-pip sudo --fix-missing",
-            "retries": 5,
-            "retry_delay_s": 5,
-            "retry_on": [
-                "lock-frontend",
-                "Unable to acquire the dpkg frontend lock",
-                "Temporary failure resolving",
-                "Could not resolve",
-                "Failed to fetch",
-            ],
-        },
-        {"name": "user_exists", "cmd": f"id -u {user} >/dev/null 2>&1 || adduser --disabled-password --gecos '' {user}", "retries": 0},
-        {"name": "add_sudo", "cmd": f"usermod -aG sudo {user}", "retries": 0},
-    ]
-    if password:
-        steps.append({"name": "set_password", "cmd": f"echo '{user}:{password}' | chpasswd", "retries": 0})
-    if ssh_key:
-        steps.append({
-            "name": "add_ssh_key",
-            "cmd": f"install -d -m 700 /home/{user}/.ssh && echo '{ssh_key}' >> /home/{user}/.ssh/authorized_keys && chown -R {user}:{user} /home/{user}/.ssh",
-            "retries": 0,
-        })
-    steps.extend([
-        {"name": "pip_upgrade", "cmd": "python3 -m pip install --upgrade pip", "retries": 0},
-        {"name": "install_portacode", "cmd": "python3 -m pip install --upgrade portacode", "retries": 0},
-        {"name": "portacode_connect", "type": "portacode_connect", "timeout_s": 30},
-    ])
-
-    results, ok = _run_setup_steps(vmid, steps, user)
+def _bootstrap_portacode(
+    vmid: int,
+    user: str,
+    password: str,
+    ssh_key: str,
+    steps: Optional[List[Dict[str, Any]]] = None,
+    progress_callback: Optional[ProgressCallback] = None,
+    start_index: int = 1,
+    total_steps: Optional[int] = None,
+) -> Tuple[str, List[Dict[str, Any]]]:
+    actual_steps = steps if steps is not None else _build_bootstrap_steps(user, password, ssh_key)
+    results, ok = _run_setup_steps(
+        vmid,
+        actual_steps,
+        user,
+        progress_callback=progress_callback,
+        start_index=start_index,
+        total_steps=total_steps,
+    )
     if not ok:
         raise RuntimeError("Portacode bootstrap steps failed.")
     key_step = next((entry for entry in results if entry.get("name") == "portacode_connect"), None)
@@ -626,6 +922,7 @@ def configure_infrastructure(token_identifier: str, token_value: str, verify_ssl
     _save_config(config)
     snapshot = build_snapshot(config)
     snapshot["node_status"] = status
+    snapshot["managed_containers"] = _get_managed_containers_summary(force=True)
     return snapshot
 
 
@@ -634,6 +931,7 @@ def get_infra_snapshot() -> Dict[str, Any]:
     snapshot = build_snapshot(config)
     if config.get("node_status"):
         snapshot["node_status"] = config["node_status"]
+    snapshot["managed_containers"] = _get_managed_containers_summary()
     return snapshot
 
 
@@ -646,6 +944,7 @@ def revert_infrastructure() -> Dict[str, Any]:
     snapshot["network"]["applied"] = False
     snapshot["network"]["message"] = "Reverted to previous network state"
     snapshot["network"]["bridge"] = DEFAULT_BRIDGE
+    snapshot["managed_containers"] = _get_managed_containers_summary(force=True)
     return snapshot
 
 
@@ -661,22 +960,22 @@ def _instantiate_container(proxmox: Any, node: str, payload: Dict[str, Any]) ->
     vmid = _allocate_vmid(proxmox)
     if not payload.get("hostname"):
         payload["hostname"] = f"ct{vmid}"
-    try:
-        upid = proxmox.nodes(node).lxc.create(
-            vmid=vmid,
-            hostname=payload["hostname"],
-            ostemplate=payload["template"],
-            rootfs=rootfs,
-            memory=int(payload["ram_mib"]),
-            swap=int(payload.get("swap_mb", 0)),
-            cores=int(payload.get("cpus", 1)),
-            cpuunits=int(payload.get("cpuunits", 256)),
-            net0=payload["net0"],
-            unprivileged=int(payload.get("unprivileged", 1)),
-            description=payload.get("description", MANAGED_MARKER),
-            password=payload.get("password") or None,
-            ssh_public_keys=payload.get("ssh_public_key") or None,
-        )
+        try:
+            upid = proxmox.nodes(node).lxc.create(
+                vmid=vmid,
+                hostname=payload["hostname"],
+                ostemplate=payload["template"],
+                rootfs=rootfs,
+                memory=int(payload["ram_mib"]),
+                swap=int(payload.get("swap_mb", 0)),
+                cores=max(int(payload.get("cores", 1)), 1),
+                cpuunits=int(payload.get("cpuunits", 256)),
+                net0=payload["net0"],
+                unprivileged=int(payload.get("unprivileged", 1)),
+                description=payload.get("description", MANAGED_MARKER),
+                password=payload.get("password") or None,
+                ssh_public_keys=payload.get("ssh_public_key") or None,
+            )
         status, elapsed = _wait_for_task(proxmox, node, upid)
         return vmid, elapsed
     except ResourceException as exc:
@@ -692,49 +991,171 @@ class CreateProxmoxContainerHandler(SyncHandler):
 
     def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
         logger.info("create_proxmox_container command received")
-        if os.geteuid() != 0:
-            logger.error("container creation rejected: not running as root")
-            raise PermissionError("Container creation requires root privileges.")
-
-        config = _load_config()
-        if not config or not config.get("token_value"):
-            logger.error("container creation rejected: infra not configured")
-            raise ValueError("Proxmox infrastructure is not configured.")
-        if not config.get("network", {}).get("applied"):
-            logger.error("container creation rejected: network bridge not applied")
-            raise RuntimeError("Proxmox bridge setup must be applied before creating containers.")
-
-        proxmox = _connect_proxmox(config)
-        node = config.get("node") or DEFAULT_NODE_NAME
-        payload = _build_container_payload(message, config)
-        payload["cpuunits"] = max(int(payload["cpus"] * 1024), 10)
-        payload["memory"] = int(payload["ram_mib"])
-        payload["node"] = node
-        logger.debug(
-            "Provisioning container node=%s template=%s ram=%s cpu=%s storage=%s",
-            node,
-            payload["template"],
-            payload["ram_mib"],
-            payload["cpus"],
-            payload["storage"],
+        request_id = message.get("request_id")
+        bootstrap_user, bootstrap_password, bootstrap_ssh_key = _get_provisioning_user_info(message)
+        bootstrap_steps = _build_bootstrap_steps(bootstrap_user, bootstrap_password, bootstrap_ssh_key)
+        total_steps = 3 + len(bootstrap_steps) + 2
+        current_step_index = 1
+
+        def _run_lifecycle_step(
+            step_name: str,
+            step_label: str,
+            start_message: str,
+            success_message: str,
+            action,
+        ):
+            nonlocal current_step_index
+            step_index = current_step_index
+            _emit_progress_event(self,
+                step_index=step_index,
+                total_steps=total_steps,
+                step_name=step_name,
+                step_label=step_label,
+                status="in_progress",
+                message=start_message,
+                phase="lifecycle",
+                request_id=request_id,
+            )
+            try:
+                result = action()
+            except Exception as exc:
+                _emit_progress_event(
+                    self,
+                    step_index=step_index,
+                    total_steps=total_steps,
+                    step_name=step_name,
+                    step_label=step_label,
+                    status="failed",
+                    message=f"{step_label} failed: {exc}",
+                    phase="lifecycle",
+                    request_id=request_id,
+                    details={"error": str(exc)},
+                )
+                raise
+            _emit_progress_event(
+                self,
+                step_index=step_index,
+                total_steps=total_steps,
+                step_name=step_name,
+                step_label=step_label,
+                status="completed",
+                message=success_message,
+                phase="lifecycle",
+                request_id=request_id,
+            )
+            current_step_index += 1
+            return result
+
+        def _validate_environment():
+            if os.geteuid() != 0:
+                raise PermissionError("Container creation requires root privileges.")
+            config = _load_config()
+            if not config or not config.get("token_value"):
+                raise ValueError("Proxmox infrastructure is not configured.")
+            if not config.get("network", {}).get("applied"):
+                raise RuntimeError("Proxmox bridge setup must be applied before creating containers.")
+            return config
+
+        config = _run_lifecycle_step(
+            "validate_environment",
+            "Validating infrastructure",
+            "Checking token, permissions, and bridge setup…",
+            "Infrastructure validated.",
+            _validate_environment,
         )
 
-        try:
+        def _create_container():
+            proxmox = _connect_proxmox(config)
+            node = config.get("node") or DEFAULT_NODE_NAME
+            payload = _build_container_payload(message, config)
+            payload["cpuunits"] = max(int(payload["cpus"] * 1024), 10)
+            payload["memory"] = int(payload["ram_mib"])
+            payload["node"] = node
+            logger.debug(
+                "Provisioning container node=%s template=%s ram=%s cpu=%s storage=%s",
+                node,
+                payload["template"],
+                payload["ram_mib"],
+                payload["cpus"],
+                payload["storage"],
+            )
             vmid, _ = _instantiate_container(proxmox, node, payload)
-        except Exception as exc:
-            logger.exception("container instantiation failed")
-            raise
-
-        payload["vmid"] = vmid
-        payload["created_at"] = datetime.utcnow().isoformat() + "Z"
-        _write_container_record(vmid, payload)
+            payload["vmid"] = vmid
+            payload["created_at"] = datetime.utcnow().isoformat() + "Z"
+            payload["status"] = "creating"
+            _write_container_record(vmid, payload)
+            return proxmox, node, vmid, payload
+
+        proxmox, node, vmid, payload = _run_lifecycle_step(
+            "create_container",
+            "Creating container",
+            "Provisioning the LXC container…",
+            "Container created.",
+            _create_container,
+        )
 
-        try:
+        def _start_container_step():
             _start_container(proxmox, node, vmid)
-            public_key, steps = _bootstrap_portacode(vmid, payload["username"], payload["password"], payload["ssh_public_key"])
-        except Exception:
-            logger.exception("failed to start/setup container %s", vmid)
-            raise
+
+        _run_lifecycle_step(
+            "start_container",
+            "Starting container",
+            "Booting the container…",
+            "Container startup completed.",
+            _start_container_step,
+        )
+        _update_container_record(vmid, {"status": "running"})
+
+        def _bootstrap_progress_callback(
+            step_index: int,
+            total: int,
+            step: Dict[str, Any],
+            status: str,
+            result: Optional[Dict[str, Any]],
+        ):
+            label = step.get("display_name") or _friendly_step_label(step.get("name", "bootstrap"))
+            error_summary = (result or {}).get("error_summary") or (result or {}).get("error")
+            attempt = (result or {}).get("attempt")
+            if status == "in_progress":
+                message_text = f"{label} is running…"
+            elif status == "completed":
+                message_text = f"{label} completed."
+            elif status == "retrying":
+                attempt_desc = f" (attempt {attempt})" if attempt else ""
+                message_text = f"{label} failed{attempt_desc}; retrying…"
+            else:
+                message_text = f"{label} failed"
+                if error_summary:
+                    message_text += f": {error_summary}"
+            details: Dict[str, Any] = {}
+            if attempt:
+                details["attempt"] = attempt
+            if error_summary:
+                details["error_summary"] = error_summary
+            _emit_progress_event(
+                self,
+                step_index=step_index,
+                total_steps=total,
+                step_name=step.get("name", "bootstrap"),
+                step_label=label,
+                status=status,
+                message=message_text,
+                phase="bootstrap",
+                request_id=request_id,
+                details=details or None,
+            )
+
+        public_key, steps = _bootstrap_portacode(
+            vmid,
+            payload["username"],
+            payload["password"],
+            payload["ssh_public_key"],
+            steps=bootstrap_steps,
+            progress_callback=_bootstrap_progress_callback,
+            start_index=current_step_index,
+            total_steps=total_steps,
+        )
+        current_step_index += len(bootstrap_steps)
 
         return {
             "event": "proxmox_container_created",
@@ -755,6 +1176,212 @@ class CreateProxmoxContainerHandler(SyncHandler):
         }
 
 
+class StartPortacodeServiceHandler(SyncHandler):
+    """Start the Portacode service inside a newly created container."""
+
+    @property
+    def command_name(self) -> str:
+        return "start_portacode_service"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        ctid = message.get("ctid")
+        if not ctid:
+            raise ValueError("ctid is required")
+        try:
+            vmid = int(ctid)
+        except ValueError:
+            raise ValueError("ctid must be an integer")
+
+        record = _read_container_record(vmid)
+        user = record.get("username")
+        password = record.get("password")
+        if not user or not password:
+            raise RuntimeError("Container credentials unavailable")
+
+        start_index = int(message.get("step_index", 1))
+        total_steps = int(message.get("total_steps", start_index + 2))
+        request_id = message.get("request_id")
+
+        auth_step_name = "setup_device_authentication"
+        auth_label = "Setting up device authentication"
+        _emit_progress_event(
+            self,
+            step_index=start_index,
+            total_steps=total_steps,
+            step_name=auth_step_name,
+            step_label=auth_label,
+            status="in_progress",
+            message="Notifying the server of the new device…",
+            phase="service",
+            request_id=request_id,
+        )
+        _emit_progress_event(
+            self,
+            step_index=start_index,
+            total_steps=total_steps,
+            step_name=auth_step_name,
+            step_label=auth_label,
+            status="completed",
+            message="Authentication metadata recorded.",
+            phase="service",
+            request_id=request_id,
+        )
+
+        install_step = start_index + 1
+        install_label = "Launching Portacode service"
+        _emit_progress_event(
+            self,
+            step_index=install_step,
+            total_steps=total_steps,
+            step_name="launch_portacode_service",
+            step_label=install_label,
+            status="in_progress",
+            message="Running sudo portacode service install…",
+            phase="service",
+            request_id=request_id,
+        )
+
+        cmd = f"su - {user} -c 'sudo -S portacode service install'"
+        res = _run_pct(vmid, cmd, input_text=password + "\n")
+
+        if res["returncode"] != 0:
+            _emit_progress_event(
+                self,
+                step_index=install_step,
+                total_steps=total_steps,
+                step_name="launch_portacode_service",
+                step_label=install_label,
+                status="failed",
+                message=f"{install_label} failed: {res.get('stderr') or res.get('stdout')}",
+                phase="service",
+                request_id=request_id,
+                details={
+                    "stderr": res.get("stderr"),
+                    "stdout": res.get("stdout"),
+                },
+            )
+            raise RuntimeError(res.get("stderr") or res.get("stdout") or "Service install failed")
+
+        _emit_progress_event(
+            self,
+            step_index=install_step,
+            total_steps=total_steps,
+            step_name="launch_portacode_service",
+            step_label=install_label,
+            status="completed",
+            message="Portacode service install finished.",
+            phase="service",
+            request_id=request_id,
+        )
+
+        return {
+            "event": "proxmox_service_started",
+            "success": True,
+            "message": "Portacode service install completed",
+            "ctid": str(vmid),
+        }
+
+
+class StartProxmoxContainerHandler(SyncHandler):
+    """Start a managed container via the Proxmox API."""
+
+    @property
+    def command_name(self) -> str:
+        return "start_proxmox_container"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        vmid = _parse_ctid(message)
+        config = _ensure_infra_configured()
+        proxmox = _connect_proxmox(config)
+        node = _get_node_from_config(config)
+        _ensure_container_managed(proxmox, node, vmid)
+
+        status, elapsed = _start_container(proxmox, node, vmid)
+        _update_container_record(vmid, {"status": "running"})
+
+        infra = get_infra_snapshot()
+        return {
+            "event": "proxmox_container_action",
+            "action": "start",
+            "success": True,
+            "ctid": str(vmid),
+            "message": f"Started container {vmid} in {elapsed:.1f}s.",
+            "details": {"exitstatus": status.get("exitstatus")},
+            "status": status.get("status"),
+            "infra": infra,
+        }
+
+
+class StopProxmoxContainerHandler(SyncHandler):
+    """Stop a managed container via the Proxmox API."""
+
+    @property
+    def command_name(self) -> str:
+        return "stop_proxmox_container"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        vmid = _parse_ctid(message)
+        config = _ensure_infra_configured()
+        proxmox = _connect_proxmox(config)
+        node = _get_node_from_config(config)
+        _ensure_container_managed(proxmox, node, vmid)
+
+        status, elapsed = _stop_container(proxmox, node, vmid)
+        final_status = status.get("status") or "stopped"
+        _update_container_record(vmid, {"status": final_status})
+
+        infra = get_infra_snapshot()
+        message_text = (
+            f"Container {vmid} is already stopped."
+            if final_status != "running" and elapsed == 0.0
+            else f"Stopped container {vmid} in {elapsed:.1f}s."
+        )
+        return {
+            "event": "proxmox_container_action",
+            "action": "stop",
+            "success": True,
+            "ctid": str(vmid),
+            "message": message_text,
+            "details": {"exitstatus": status.get("exitstatus")},
+            "status": final_status,
+            "infra": infra,
+        }
+
+
+class RemoveProxmoxContainerHandler(SyncHandler):
+    """Delete a managed container via the Proxmox API."""
+
+    @property
+    def command_name(self) -> str:
+        return "remove_proxmox_container"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        vmid = _parse_ctid(message)
+        config = _ensure_infra_configured()
+        proxmox = _connect_proxmox(config)
+        node = _get_node_from_config(config)
+        _ensure_container_managed(proxmox, node, vmid)
+
+        stop_status, stop_elapsed = _stop_container(proxmox, node, vmid)
+        delete_status, delete_elapsed = _delete_container(proxmox, node, vmid)
+        _remove_container_record(vmid)
+
+        infra = get_infra_snapshot()
+        return {
+            "event": "proxmox_container_action",
+            "action": "remove",
+            "success": True,
+            "ctid": str(vmid),
+            "message": f"Deleted container {vmid} in {delete_elapsed:.1f}s.",
+            "details": {
+                "stop_exitstatus": stop_status.get("exitstatus"),
+                "delete_exitstatus": delete_status.get("exitstatus"),
+            },
+            "status": "deleted",
+            "infra": infra,
+        }
+
+
 class ConfigureProxmoxInfraHandler(SyncHandler):
     @property
     def command_name(self) -> str: