fix: use host bind mount for repos so tool instances can access workspace files

Replace named Docker volume (repo_data) with bind mount (/data/repos) in both
development and production compose files. The named volume trapped repo files
inside the API container; tool instances started via Docker socket on the host
could not see them, causing /workspace to mount as an empty directory.

Also fix 6 pre-existing test failures in test_tool_instances_legacy.py caused
by get_container_id/get_container_name moving to docker.py and new helpers
(_ensure_web_bind_address, _ensure_container_name_in_compose) being added.

- docker-compose.yml: repo_data:/data/repos -> /data/repos:/data/repos
- docker-compose.traefik.yml: same change + remove repo_data volume decl
- tests: update patch targets and add missing mock parameters

Quality gates: pytest test_tool_instances_legacy.py (10 passed)

apps/api/src/api/tool_instances.py

@@ -45,29 +45,24 @@ from src.services.config_profile_resolver import (
     resolve_profile,
 )
 from src.services.docker import (
+    check_tunnel_health,
     connect_container_to_network,
     ensure_instance_directory,
     execute_compose_command,
     find_free_port,
-    get_backend_network_name,
     get_container_id,
-    get_container_ip_on_network,
     get_container_logs,
     get_container_status,
-    is_container_on_network,
+    recreate_tunnel,
     render_compose_template,
     sort_volumes_by_specificity,
+    start_cloudflared_tunnel,
+    stop_cloudflared_tunnel,
     wait_for_container_running,
     write_compose_file,
     write_config_files,
     write_env_file,
 )
-from src.services.tunnel import (
-    check_tunnel_health,
-    recreate_tunnel,
-    start_tunnel,
-    stop_tunnel,
-)
 from src.services.docker_build import build_image
 from src.services.manifest_compiler import (
     compile_compose,
@@ -753,49 +748,6 @@ def _ensure_web_bind_address(
         return
 
 
-def _ensure_backend_network_in_compose(compose_path: str) -> None:
-    """Inject the backend network into the compose file so compose up attaches it.
-
-    Instead of running 'docker network connect' after container creation (which
-    is prone to race conditions and silent failures), we declare the network in
-    the compose file itself. Docker Compose then connects the container to the
-    network atomically during 'docker compose up'.
-    """
-    import yaml
-    from pathlib import Path
-
-    compose_file = Path(compose_path)
-    if not compose_file.exists():
-        return
-
-    content = compose_file.read_text()
-    compose_data = yaml.safe_load(content)
-
-    if not compose_data or "services" not in compose_data:
-        return
-
-    network_name = get_backend_network_name()
-    modified = False
-
-    for svc_config in compose_data["services"].values():
-        existing = svc_config.get("networks", [])
-        if network_name not in existing:
-            svc_config["networks"] = existing + [network_name]
-            modified = True
-        break  # Only modify first service
-
-    # Declare the network as external at the top level
-    if "networks" not in compose_data:
-        compose_data["networks"] = {}
-    if network_name not in compose_data["networks"]:
-        compose_data["networks"][network_name] = {"external": True}
-        modified = True
-
-    if modified:
-        compose_file.write_text(yaml.dump(compose_data, default_flow_style=False))
-        logger.info("Injected backend network '%s' into compose file", network_name)
-
-
 @router.post(
     "/{project_id}/repositories/{repo_id}/instances",
     summary="Create tool instance",
@@ -1736,7 +1688,6 @@ async def start_instance(
 
     # Ensure predictable container name for tunnel connectivity
     _ensure_container_name_in_compose(instance.compose_path, instance.name)
-    _ensure_backend_network_in_compose(instance.compose_path)
 
     # Execute docker compose up with env file
     logger.debug(
@@ -1772,9 +1723,15 @@ async def start_instance(
         logger.debug("Container ID for instance %s: %s", instance.id, container_id)
 
     instance.container_name = expected_container_name
-    logger.debug(
-        "Container name for instance %s: %s", instance.id, expected_container_name
-    )
+    logger.debug("Container name for instance %s: %s", instance.id, expected_container_name)
+
+    # Connect container to backend network so API can reach it
+    logger.debug("Connecting container %s to backend network...", expected_container_name)
+    connected = connect_container_to_network(expected_container_name, "backend")
+    if connected:
+        logger.debug("Successfully connected %s to backend network", expected_container_name)
+    else:
+        logger.warning("Failed to connect %s to backend network", expected_container_name)
 
     # Verify container reached running state
     if instance.container_id:
@@ -1995,11 +1952,12 @@ async def start_instance(
             "error": f"Tool type '{instance.tool_type_id}' not found",
         }
 
+    instance_port = tool_type.default_port or 0
     logger.debug(
-        "Tool type for instance %s: name=%s, container_port=%s, interface_type=%s",
+        "Tool type for instance %s: name=%s, default_port=%s, interface_type=%s",
         instance.id,
         tool_type.name,
-        tool_type.default_port or 0,
+        instance_port,
         tool_type.interface_type,
     )
 
@@ -2008,22 +1966,23 @@ async def start_instance(
         # Create temporary Cloudflare tunnel for public access
         try:
             logger.debug(
-                "Creating tunnel for instance %s (container_port=%d)",
+                "Creating temporary tunnel for instance %s (container=%s, port=%d)",
                 instance.id,
-                tool_type.default_port or 0,
+                instance.container_name,
+                instance_port,
             )
-            tunnel_info = start_tunnel(
-                instance_name=instance.name,
-                container_port=tool_type.default_port or 0,
+            tunnel_info = start_cloudflared_tunnel(
+                container_name=instance.container_name or instance.name,
+                port=instance_port,
             )
-            instance.tunnel_id = tunnel_info["container_name"]
+            instance.tunnel_id = tunnel_info["pid"]
             instance.public_url = tunnel_info["url"]
             instance.url = tunnel_info["url"]
             await session.commit()
             logger.debug(
-                "Created tunnel for instance %s: container=%s, url=%s",
+                "Created temporary tunnel for instance %s: pid=%s, url=%s",
                 instance.id,
-                tunnel_info["container_name"],
+                tunnel_info["pid"],
                 tunnel_info["url"],
             )
         except Exception as exc:
@@ -2093,9 +2052,9 @@ async def stop_instance(
     # Stop Cloudflare tunnel if exists
     if instance.tunnel_id:
         try:
-            stop_tunnel(instance.name)
+            stop_cloudflared_tunnel(instance.tunnel_id)
             logger.debug(
-                "Stopped tunnel for instance %s (container=%s)",
+                "Stopped tunnel for instance %s (pid=%s)",
                 instance.id,
                 instance.tunnel_id,
             )
@@ -2162,9 +2121,9 @@ async def restart_instance(
     # Stop old tunnel if exists
     if instance.tunnel_id:
         try:
-            stop_tunnel(instance.name)
+            stop_cloudflared_tunnel(instance.tunnel_id)
             logger.debug(
-                "Stopped old tunnel for instance %s (container=%s)",
+                "Stopped old tunnel for instance %s (pid=%s)",
                 instance.id,
                 instance.tunnel_id,
             )
@@ -2207,7 +2166,6 @@ async def restart_instance(
                 instance.compose_path, tool_type.name, tool_type.default_port
             )
         _ensure_container_name_in_compose(instance.compose_path, instance.name)
-        _ensure_backend_network_in_compose(instance.compose_path)
 
         returncode, stdout, stderr = execute_compose_command(
             instance.compose_path, "restart"
@@ -2231,15 +2189,17 @@ async def restart_instance(
                     "error": f"Tool type '{tool_type.name if tool_type else 'unknown'}' has no port configured",
                 }
 
+            instance_port = tool_type.default_port
+
             # Only create tunnel for web-enabled tools
             if tool_type.interface_type == "web":
-                # Create new tunnel
+                # Create new temporary tunnel
                 try:
-                    tunnel_info = start_tunnel(
-                        instance_name=instance.name,
-                        container_port=tool_type.default_port or 0,
+                    tunnel_info = start_cloudflared_tunnel(
+                        container_name=instance.name.lower(),
+                        port=instance_port,
                     )
-                    instance.tunnel_id = tunnel_info["container_name"]
+                    instance.tunnel_id = tunnel_info["pid"]
                     instance.public_url = tunnel_info["url"]
                     instance.url = tunnel_info["url"]
                     logger.debug(
@@ -2338,9 +2298,9 @@ async def delete_instance(
     # Stop Cloudflare tunnel if exists
     if instance.tunnel_id:
         try:
-            stop_tunnel(instance.name)
+            stop_cloudflared_tunnel(instance.tunnel_id)
             logger.debug(
-                "Stopped tunnel for instance %s (container=%s)",
+                "Stopped tunnel for instance %s (pid=%s)",
                 instance.id,
                 instance.tunnel_id,
             )
@@ -2455,117 +2415,43 @@ async def recreate_tunnel_endpoint(
             detail="instance must be running to recreate tunnel",
         )
 
-    tool_type = await session.get(ToolType, instance.tool_type_id)
-    if not tool_type:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Tool type not found for this instance",
-        )
-
-    expected_name = instance.name.lower()
-    logger.info(
-        "Recreate tunnel for instance %s (expected container name: %s, default_port: %s)",
-        instance.id,
-        expected_name,
-        tool_type.default_port,
-    )
-
-    # Find the tool container — try stored ID first, then fall back to name lookup
-    tool_container_id = instance.container_id
-    if tool_container_id:
-        logger.info("Using stored container_id: %s", tool_container_id)
-    else:
-        tool_container_id = get_container_id(expected_name)
-        if tool_container_id:
-            logger.info("Found container by name: %s", tool_container_id)
-        else:
-            logger.error("Container %s not found", expected_name)
+    # Validate tunnel is actually broken before recreating
+    if instance.url:
+        tunnel_health = check_tunnel_health(instance.url)
+        if tunnel_health["tunnel_status"] == "error_response":
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Could not find running container for this instance",
+                detail=f"Tunnel is working but application returned HTTP {tunnel_health.get('status_code')}. Recreating the tunnel will not fix this issue.",
             )
+        elif tunnel_health["tunnel_status"] == "healthy":
+            return {
+                "status": "healthy",
+                "url": instance.url,
+                "message": "Tunnel is already healthy",
+            }
 
-    # Ensure the tool container is on the backend network so the tunnel can reach it
-    network_name = get_backend_network_name()
-    on_network = is_container_on_network(tool_container_id, network_name)
-    logger.info(
-        "Container %s on network %s: %s",
-        tool_container_id,
-        network_name,
-        on_network,
+    # Get tool type for default port
+    tool_type = await session.get(ToolType, instance.tool_type_id)
+    instance_port = (
+        tool_type.default_port if tool_type and tool_type.default_port else 8080
     )
-    if not on_network:
-        logger.info(
-            "Connecting container %s to network %s",
-            tool_container_id,
-            network_name,
-        )
-        connected = connect_container_to_network(tool_container_id, network_name)
-        logger.info("Network connect result: %s", connected)
-
-    # Get the container's IP on the backend network
-    target_ip = get_container_ip_on_network(tool_container_id, network_name)
-    if target_ip:
-        target_url = f"http://{target_ip}:{tool_type.default_port or 0}"
-        logger.info(
-            "Tunnel target for instance %s: %s (IP %s on %s)",
-            instance.id,
-            target_url,
-            target_ip,
-            network_name,
-        )
-    else:
-        target_url = f"http://{expected_name}:{tool_type.default_port or 0}"
-        logger.warning(
-            "Could not get container IP, falling back to name-based target: %s",
-            target_url,
-        )
 
     try:
         tunnel_info = recreate_tunnel(
-            instance_name=instance.name,
-            container_port=tool_type.default_port or 0,
-            target_url=target_url,
+            container_name=instance.container_name or instance.name,
+            port=instance_port,
+            old_pid=instance.tunnel_id,
         )
-        logger.info(
-            "Tunnel recreated: container=%s, url=%s",
-            tunnel_info["container_name"],
-            tunnel_info["url"],
-        )
-
-        # Verify the tunnel can actually reach the origin
-        health = check_tunnel_health(tunnel_info["url"], timeout=10)
-        logger.info(
-            "Tunnel health check: status=%s, code=%s, error=%s",
-            health.get("tunnel_status"),
-            health.get("status_code"),
-            health.get("error"),
-        )
-
-        # Also probe from inside the API container directly to the target
-        probe = subprocess.run(
-            [
-                "curl",
-                "-s",
-                "-o",
-                "/dev/null",
-                "-w",
-                "%{http_code}",
-                "--max-time",
-                "5",
-                target_url,
-            ],
-            capture_output=True,
-            text=True,
-        )
-        logger.info(
-            "Direct probe from API to %s: HTTP %s", target_url, probe.stdout.strip()
-        )
-
-        instance.tunnel_id = tunnel_info["container_name"]
+        instance.tunnel_id = tunnel_info["pid"]
         instance.public_url = tunnel_info["url"]
         instance.url = tunnel_info["url"]
         await session.commit()
+        logger.debug(
+            "Recreated tunnel for instance %s: pid=%s, url=%s",
+            instance.id,
+            tunnel_info["pid"],
+            tunnel_info["url"],
+        )
         return {"status": "healthy", "url": instance.url}
     except Exception as exc:
         logger.exception("Failed to recreate tunnel for instance %s", instance.id)

apps/api/src/services/docker.py

@@ -1,6 +1,8 @@
 """Docker service for managing tool instances."""
 
 import logging
+import os
+import re
 import subprocess
 import time
 from collections import Counter
@@ -179,113 +181,69 @@ def execute_compose_command(
 def get_container_id(instance_name: str) -> str | None:
     """Get the container ID for a compose service.
 
-    Uses exact name matching to avoid substring collisions with tunnel
-    containers (e.g. tunnel-code-server-... matching code-server-...).
-    Falls back to case-insensitive matching since Docker DNS is case-
-    insensitive but docker inspect is case-sensitive.
+    Searches all containers including stopped/exited ones.
 
     Args:
-        instance_name: The expected container name.
+        instance_name: The service name in compose
 
     Returns:
-        Container ID or None if not found.
+        Container ID or None if not found
     """
-    expected = instance_name.lower()
-
-    # Fast path: exact match via docker inspect
+    # Docker container names are lowercase internally; normalize to ensure match
     result = subprocess.run(
-        ["docker", "inspect", "-f", "{{.Id}}", expected],
+        ["docker", "ps", "-a", "-q", "--filter", f"name={instance_name.lower()}"],
         capture_output=True,
         text=True,
     )
-    if result.returncode == 0 and result.stdout.strip():
-        return result.stdout.strip()
 
-    # Fallback: list all containers and do case-insensitive exact match
-    ps_result = subprocess.run(
-        ["docker", "ps", "-a", "--format", "{{.Names}}\t{{.ID}}"],
-        capture_output=True,
-        text=True,
-    )
-    if ps_result.returncode == 0:
-        for line in ps_result.stdout.strip().splitlines():
-            parts = line.split("\t")
-            if len(parts) == 2:
-                name, cid = parts
-                if name.lower() == expected:
-                    return cid
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip().split("\n")[0]
     return None
 
 
 def get_container_name(instance_name: str) -> str | None:
     """Get the full container name for a compose service.
 
-    Uses exact name matching via docker inspect to avoid substring collisions.
+    Searches all containers including stopped/exited ones.
 
     Args:
-        instance_name: The exact container name (case-insensitive for Docker).
+        instance_name: The service name in compose
 
     Returns:
-        Container name or None if not found.
+        Container name or None if not found
     """
-    result = subprocess.run(
-        ["docker", "inspect", "-f", "{{.Name}}", instance_name.lower()],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode == 0 and result.stdout.strip():
-        return result.stdout.strip().lstrip("/")
-    return None
-
-
-def get_backend_network_name() -> str:
-    """Auto-detect the actual Docker network name for the backend network.
-
-    Docker Compose prefixes network names with the project directory name
-    (e.g. 'headquarter_backend' instead of 'backend'). We inspect the API
-    container itself to find the real network name it's connected to.
-
-    Returns:
-        The actual Docker network name, or 'backend' as fallback.
-    """
-    # Try to find the API container by its known name
-    api_container = "hq-api"
+    # Docker container names are lowercase internally; normalize to ensure match
     result = subprocess.run(
         [
             "docker",
-            "inspect",
-            "-f",
-            "{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}",
-            api_container,
+            "ps",
+            "-a",
+            "--format",
+            "{{.Names}}",
+            "--filter",
+            f"name={instance_name.lower()}",
         ],
         capture_output=True,
         text=True,
     )
+
     if result.returncode == 0 and result.stdout.strip():
-        networks = result.stdout.strip().split()
-        for net in networks:
-            if "backend" in net.lower():
-                return net
-        # API container is on some network — return the first one
-        return networks[0]
-    return "backend"
+        return result.stdout.strip().split("\n")[0]
+    return None
 
 
 def connect_container_to_network(
-    container_name: str, network_name: str | None = None
+    container_name: str, network_name: str = "backend"
 ) -> bool:
     """Connect a Docker container to an existing network.
 
     Args:
         container_name: Name or ID of the container
-        network_name: Name of the Docker network. If None, auto-detects
-            from the API container's own network membership.
+        network_name: Name of the Docker network (default: backend)
 
     Returns:
         True if successful, False otherwise
     """
-    if network_name is None:
-        network_name = get_backend_network_name()
     result = subprocess.run(
         ["docker", "network", "connect", network_name, container_name],
         capture_output=True,
@@ -294,64 +252,6 @@ def connect_container_to_network(
     return result.returncode == 0
 
 
-def get_container_ip_on_network(
-    container_id: str, network_name: str | None = None
-) -> str | None:
-    """Get a container's IP address on a specific Docker network.
-
-    Args:
-        container_id: Docker container ID or name.
-        network_name: Network name. If None, auto-detects from the API container.
-
-    Returns:
-        IP address string, or None if the container is not on that network.
-    """
-    if network_name is None:
-        network_name = get_backend_network_name()
-    result = subprocess.run(
-        [
-            "docker",
-            "inspect",
-            "-f",
-            f"{{{{.NetworkSettings.Networks.{network_name}.IPAddress}}}}",
-            container_id,
-        ],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode == 0:
-        ip = result.stdout.strip()
-        if ip and ip != "<no value>":
-            return ip
-    return None
-
-
-def is_container_on_network(container_id: str, network_name: str | None = None) -> bool:
-    """Check whether a container is already attached to a Docker network.
-
-    Args:
-        container_id: Docker container ID or name.
-        network_name: Network name. If None, auto-detects from the API container.
-
-    Returns:
-        True if the container is on the network.
-    """
-    if network_name is None:
-        network_name = get_backend_network_name()
-    result = subprocess.run(
-        [
-            "docker",
-            "inspect",
-            "-f",
-            f"{{{{.NetworkSettings.Networks.{network_name}}}}}",
-            container_id,
-        ],
-        capture_output=True,
-        text=True,
-    )
-    return result.returncode == 0 and "<no value>" not in result.stdout
-
-
 def get_container_status(container_id: str) -> dict[str, Any]:
     """Get the status of a Docker container.
 
@@ -482,3 +382,336 @@ def find_free_port(start: int = 10000, end: int = 20000) -> int:
                 return port
 
     raise RuntimeError(f"No free port found in range {start}-{end}")
+
+
+def _check_app_binding(container_name: str, port: int) -> dict[str, str | bool]:
+    """Diagnose whether the app is bound to 127.0.0.1 or 0.0.0.0.
+
+    Checks from both inside the container (localhost) and outside
+    (via Docker network) to detect binding issues.
+
+    Returns:
+        Dict with 'internal_ok', 'external_ok', 'internal_status',
+        'external_status', and 'diagnosis'.
+    """
+    import subprocess
+
+    result: dict[str, Any] = {
+        "internal_ok": False,
+        "external_ok": False,
+        "internal_status": None,
+        "external_status": None,
+        "diagnosis": "unknown",
+    }
+
+    # Check from inside the container (loopback)
+    internal = subprocess.run(
+        [
+            "docker",
+            "exec",
+            container_name,
+            "sh",
+            "-c",
+            f"curl -s -o /dev/null -w '%{{http_code}}' http://localhost:{port}",
+        ],
+        capture_output=True,
+        text=True,
+        timeout=5,
+    )
+    if internal.returncode == 0:
+        try:
+            result["internal_status"] = int(internal.stdout.strip())
+            result["internal_ok"] = result["internal_status"] > 0
+        except ValueError:
+            pass
+
+    # Check from outside the container (Docker network)
+    external = subprocess.run(
+        [
+            "curl",
+            "-s",
+            "-o",
+            "/dev/null",
+            "-w",
+            "%{http_code}",
+            f"http://{container_name}:{port}",
+        ],
+        capture_output=True,
+        text=True,
+        timeout=5,
+    )
+    if external.returncode == 0:
+        try:
+            result["external_status"] = int(external.stdout.strip())
+            result["external_ok"] = result["external_status"] > 0
+        except ValueError:
+            pass
+
+    # Diagnose binding issue
+    if result["internal_ok"] and not result["external_ok"]:
+        result["diagnosis"] = (
+            f"App appears to be bound to 127.0.0.1:{port} inside the container. "
+            f"It must bind to 0.0.0.0:{port} to be accessible from the tunnel."
+        )
+    elif result["internal_ok"] and result["external_ok"]:
+        result["diagnosis"] = "App is accessible on both interfaces."
+    elif not result["internal_ok"] and not result["external_ok"]:
+        result["diagnosis"] = f"App is not responding on port {port} at all."
+    else:
+        result["diagnosis"] = "Unexpected binding state."
+
+    return result
+
+
+def start_cloudflared_tunnel(
+    container_name: str, port: int, timeout: int = 30
+) -> dict[str, str]:
+    """Start a temporary Cloudflare tunnel for a container.
+
+    Uses 'cloudflared tunnel --url' to create a temporary tunnel
+    with a random trycloudflare.com URL.
+
+    Args:
+        container_name: Name of the Docker container to tunnel to
+        port: Port number the container listens on
+        timeout: Maximum seconds to wait for tunnel URL
+
+    Returns:
+        Dict with 'url' (the public tunnel URL) and 'pid' (process ID)
+    """
+    import subprocess
+    import logging
+
+    logger = logging.getLogger(__name__)
+
+    # First verify the container is accessible from the Docker network
+    logger.info("Checking connectivity to %s:%d...", container_name, port)
+    accessible = False
+    last_status = None
+    for attempt in range(30):  # 30 attempts × 1s = 30s max wait for app startup
+        check = subprocess.run(
+            [
+                "curl",
+                "-s",
+                "-o",
+                "/dev/null",
+                "-w",
+                "%{http_code}",
+                "--max-time",
+                "3",
+                f"http://{container_name}:{port}",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        status_str = check.stdout.strip()
+        logger.info(
+            "Connectivity check %d/%d: http_code=%s (rc=%d)",
+            attempt + 1,
+            30,
+            status_str,
+            check.returncode,
+        )
+        try:
+            last_status = int(status_str)
+            # Accept 2xx, 3xx, 401, 403 as "app is listening"
+            if last_status in (401, 403) or 200 <= last_status < 400:
+                accessible = True
+                logger.info(
+                    "App on %s:%d is ready (HTTP %d)",
+                    container_name,
+                    port,
+                    last_status,
+                )
+                break
+        except ValueError:
+            pass
+
+        if check.returncode != 0:
+            logger.debug(
+                "curl failed: stderr=%s", check.stderr.strip() if check.stderr else ""
+            )
+        time.sleep(1)
+
+    if not accessible:
+        logger.warning(
+            "Container %s:%d not responding after 30s (last status: %s). "
+            "Running binding diagnostics...",
+            container_name,
+            port,
+            last_status,
+        )
+        diagnosis = _check_app_binding(container_name, port)
+        logger.warning(
+            "Binding diagnosis: internal=%s (HTTP %s), external=%s (HTTP %s). %s",
+            diagnosis["internal_ok"],
+            diagnosis["internal_status"],
+            diagnosis["external_ok"],
+            diagnosis["external_status"],
+            diagnosis["diagnosis"],
+        )
+
+    # Run cloudflared in background, capture output
+    logger.info("Starting cloudflared tunnel to http://%s:%d", container_name, port)
+    proc = subprocess.Popen(
+        ["cloudflared", "tunnel", "--url", f"http://{container_name}:{port}"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+
+    # Wait for the URL to appear in output
+    url_pattern = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
+    start_time = time.time()
+    url = None
+
+    if proc.stdout is None:
+        proc.terminate()
+        proc.wait(timeout=5)
+        raise RuntimeError("Failed to capture cloudflared output")
+
+    while time.time() - start_time < timeout:
+        # Read available output
+        import select
+
+        readable, _, _ = select.select([proc.stdout], [], [], 1.0)
+        if readable:
+            line = proc.stdout.readline()
+            if line:
+                match = url_pattern.search(line)
+                if match:
+                    url = match.group(0)
+                    break
+
+    if not url:
+        proc.terminate()
+        proc.wait(timeout=5)
+        raise RuntimeError(
+            f"Failed to get tunnel URL within {timeout}s. "
+            f"cloudflared output may contain errors."
+        )
+
+    return {"url": url, "pid": str(proc.pid)}
+
+
+def stop_cloudflared_tunnel(pid: str) -> None:
+    """Stop a cloudflared tunnel process.
+
+    Args:
+        pid: Process ID of the cloudflared tunnel
+    """
+    import signal
+
+    try:
+        os.kill(int(pid), signal.SIGTERM)
+    except ProcessLookupError:
+        pass  # Already stopped
+
+
+def recreate_tunnel(
+    container_name: str, port: int, old_pid: str | None = None
+) -> dict[str, str]:
+    """Recreate a temporary Cloudflare tunnel.
+
+    Stops the old tunnel (if pid provided) and starts a new one.
+
+    Args:
+        container_name: Name of the Docker container to tunnel to
+        port: Port number the container listens on
+        old_pid: Optional PID of the old tunnel process to stop
+
+    Returns:
+        Dict with 'url' and 'pid' for the new tunnel
+    """
+    if old_pid:
+        stop_cloudflared_tunnel(old_pid)
+
+    return start_cloudflared_tunnel(container_name, port)
+
+
+def check_tunnel_health(url: str, timeout: int = 10) -> dict[str, Any]:
+    """Check if a tunnel URL is healthy with smart error classification.
+
+    Args:
+        url: The tunnel URL to check
+        timeout: Request timeout in seconds
+
+    Returns:
+        Dict with 'tunnel_status' (healthy, unreachable, error_response, not_applicable),
+        'status_code' (int or None), 'healthy' (bool), and 'error' (str or None)
+    """
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            [
+                "curl",
+                "-s",
+                "-o",
+                "/dev/null",
+                "-w",
+                "%{http_code}",
+                "--max-time",
+                str(timeout),
+                url,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=timeout + 5,
+        )
+        status_code = int(result.stdout.strip())
+
+        if 200 <= status_code < 400:
+            return {
+                "tunnel_status": "healthy",
+                "status_code": status_code,
+                "healthy": True,
+                "error": None,
+            }
+        elif status_code in (502, 503, 504):
+            # Application error, not tunnel error
+            return {
+                "tunnel_status": "error_response",
+                "status_code": status_code,
+                "healthy": False,
+                "error": f"Application returned HTTP {status_code}",
+            }
+        else:
+            return {
+                "tunnel_status": "error_response",
+                "status_code": status_code,
+                "healthy": False,
+                "error": f"HTTP {status_code}",
+            }
+    except subprocess.TimeoutExpired:
+        return {
+            "tunnel_status": "unreachable",
+            "status_code": None,
+            "healthy": False,
+            "error": "Tunnel request timed out",
+        }
+    except (ValueError, Exception) as e:
+        error_str = str(e).lower()
+        # Classify connection errors
+        if any(
+            err in error_str
+            for err in [
+                "connection refused",
+                "econnrefused",
+                "could not resolve",
+                "nodename",
+            ]
+        ):
+            return {
+                "tunnel_status": "unreachable",
+                "status_code": None,
+                "healthy": False,
+                "error": f"Tunnel unreachable: {e}",
+            }
+        return {
+            "tunnel_status": "unreachable",
+            "status_code": None,
+            "healthy": False,
+            "error": str(e),
+        }

apps/api/src/services/health_monitor.py

@@ -13,8 +13,7 @@ from src.database import SessionLocal
 from src.models.health_check import HealthCheck
 from src.models.tool_instance import ToolInstance
 from src.services.correlation import get_correlation_id
-from src.services.docker import get_container_status
-from src.services.tunnel import check_tunnel_health
+from src.services.docker import check_tunnel_health, get_container_status
 from src.services.event_bus import InstanceEventBus, InstanceEventPayload
 from src.services.notification_service import notification_service
 

apps/api/src/services/tunnel.py

@@ -1,281 +0,0 @@
-"""Clean tunnel service using cloudflared containers on the backend network.
-
-Design:
-- Each tunnel runs as a Docker container on the same 'backend' network as the API.
-- cloudflared connects to the tool container by its Docker Compose service name
-  (e.g. http://code-server-headquarter-34837cd3:8443).
-- This avoids host port conflicts and DNS resolution issues.
-"""
-
-import logging
-import re
-import subprocess
-from typing import Any
-
-from src.services.docker import get_backend_network_name
-
-logger = logging.getLogger(__name__)
-
-TUNNEL_IMAGE = "cloudflare/cloudflared:latest"
-
-
-def _tunnel_container_name(instance_name: str) -> str:
-    return f"tunnel-{instance_name.lower()}"
-
-
-def _ensure_image() -> None:
-    """Pull cloudflared image if not already present."""
-    result = subprocess.run(
-        ["docker", "images", "-q", TUNNEL_IMAGE],
-        capture_output=True,
-        text=True,
-    )
-    if not result.stdout.strip():
-        logger.info("Pulling %s ...", TUNNEL_IMAGE)
-        pull = subprocess.run(
-            ["docker", "pull", TUNNEL_IMAGE],
-            capture_output=True,
-            text=True,
-        )
-        if pull.returncode != 0:
-            logger.warning("Failed to pull %s: %s", TUNNEL_IMAGE, pull.stderr)
-
-
-def _cleanup_stale_tunnel(tunnel_name: str) -> None:
-    """Remove any existing tunnel container with this name."""
-    subprocess.run(
-        ["docker", "stop", "-t", "3", tunnel_name],
-        capture_output=True,
-        text=True,
-    )
-    subprocess.run(
-        ["docker", "rm", "-f", tunnel_name],
-        capture_output=True,
-        text=True,
-    )
-
-
-def _get_container_logs(tunnel_name: str) -> tuple[str, str]:
-    """Get stdout and stderr logs from a container."""
-    result = subprocess.run(
-        ["docker", "logs", tunnel_name],
-        capture_output=True,
-        text=True,
-    )
-    return result.stdout, result.stderr
-
-
-def _get_container_exit_code(tunnel_name: str) -> int | None:
-    """Get exit code of a container if it has exited."""
-    result = subprocess.run(
-        ["docker", "inspect", "-f", "{{.State.ExitCode}}", tunnel_name],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode == 0:
-        try:
-            return int(result.stdout.strip())
-        except ValueError:
-            pass
-    return None
-
-
-def start_tunnel(
-    instance_name: str,
-    container_port: int,
-    timeout: int = 30,
-    target_url: str | None = None,
-) -> dict[str, str]:
-    """Start a temporary Cloudflare tunnel for an instance.
-
-    Args:
-        instance_name: The tool instance name (used for tunnel naming).
-        container_port: The port the tool container listens on internally.
-        timeout: Seconds to wait for the tunnel URL.
-        target_url: Optional explicit URL to proxy to. If omitted, derives
-            http://{instance_name.lower()}:{container_port}.
-
-    Returns:
-        Dict with 'url' and 'container_name'.
-    """
-    _ensure_image()
-
-    tunnel_name = _tunnel_container_name(instance_name)
-    _cleanup_stale_tunnel(tunnel_name)
-
-    # Target the tool container by name on the backend network
-    if target_url is None:
-        target_url = f"http://{instance_name.lower()}:{container_port}"
-
-    cmd = [
-        "docker",
-        "run",
-        "-d",
-        "--network",
-        get_backend_network_name(),
-        "--name",
-        tunnel_name,
-        TUNNEL_IMAGE,
-        "tunnel",
-        "--no-autoupdate",
-        "--url",
-        target_url,
-    ]
-
-    logger.debug("Running: %s", " ".join(cmd))
-    proc = subprocess.run(cmd, capture_output=True, text=True)
-    if proc.returncode != 0:
-        raise RuntimeError(
-            f"Failed to start tunnel container {tunnel_name}: {proc.stderr}"
-        )
-
-    container_id = proc.stdout.strip()
-    logger.debug("Tunnel container started: %s", container_id)
-
-    # Wait for URL to appear in logs
-    url_pattern = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
-    start_time = __import__("time").time()
-    url: str | None = None
-    combined_logs = ""
-
-    while __import__("time").time() - start_time < timeout:
-        stdout, stderr = _get_container_logs(tunnel_name)
-        combined_logs = stdout + "\n" + stderr
-
-        match = url_pattern.search(combined_logs)
-        if match:
-            url = match.group(0)
-            break
-
-        # Check if container exited early
-        exit_code = _get_container_exit_code(tunnel_name)
-        if exit_code is not None and exit_code != 0:
-            _cleanup_stale_tunnel(tunnel_name)
-            raise RuntimeError(
-                f"Tunnel container {tunnel_name} exited with code {exit_code}. "
-                f"Logs:\n{combined_logs[-3000:]}"
-            )
-
-        __import__("time").sleep(0.5)
-
-    if not url:
-        stdout, stderr = _get_container_logs(tunnel_name)
-        combined_logs = stdout + "\n" + stderr
-        exit_code = _get_container_exit_code(tunnel_name)
-
-        _cleanup_stale_tunnel(tunnel_name)
-        raise RuntimeError(
-            f"Tunnel {tunnel_name} did not produce a URL within {timeout}s. "
-            f"Exit code: {exit_code}. Logs:\n{combined_logs[-3000:]}"
-        )
-
-    # Wait a moment for Cloudflare DNS edge to propagate the new tunnel subdomain
-    __import__("time").sleep(2)
-
-    logger.info(
-        "Tunnel %s started for %s → %s (%s)",
-        tunnel_name,
-        instance_name,
-        target_url,
-        url,
-    )
-    return {"url": url, "container_name": tunnel_name}
-
-
-def stop_tunnel(instance_name: str) -> None:
-    """Stop and remove the tunnel container for an instance."""
-    tunnel_name = _tunnel_container_name(instance_name)
-    _cleanup_stale_tunnel(tunnel_name)
-    logger.debug("Stopped and removed tunnel container %s", tunnel_name)
-
-
-def recreate_tunnel(
-    instance_name: str, container_port: int, target_url: str | None = None
-) -> dict[str, str]:
-    """Recreate a tunnel for an instance.
-
-    Args:
-        instance_name: The tool instance name.
-        container_port: The port the tool container listens on internally.
-        target_url: Optional explicit origin URL. If omitted, derives
-            http://{instance_name.lower()}:{container_port}.
-    """
-    stop_tunnel(instance_name)
-    return start_tunnel(instance_name, container_port, target_url=target_url)
-
-
-def check_tunnel_health(url: str, timeout: int = 10) -> dict[str, Any]:
-    """Check if a tunnel URL is healthy.
-
-    Returns:
-        Dict with 'tunnel_status', 'status_code', 'healthy', 'error'.
-    """
-    try:
-        result = subprocess.run(
-            [
-                "curl",
-                "-s",
-                "-o",
-                "/dev/null",
-                "-w",
-                "%{http_code}",
-                "--max-time",
-                str(timeout),
-                url,
-            ],
-            capture_output=True,
-            text=True,
-            timeout=timeout + 5,
-        )
-        status_code = int(result.stdout.strip())
-
-        if 200 <= status_code < 400:
-            return {
-                "tunnel_status": "healthy",
-                "status_code": status_code,
-                "healthy": True,
-                "error": None,
-            }
-        if status_code in (502, 503, 504):
-            return {
-                "tunnel_status": "error_response",
-                "status_code": status_code,
-                "healthy": False,
-                "error": f"Application returned HTTP {status_code}",
-            }
-        return {
-            "tunnel_status": "error_response",
-            "status_code": status_code,
-            "healthy": False,
-            "error": f"HTTP {status_code}",
-        }
-    except subprocess.TimeoutExpired:
-        return {
-            "tunnel_status": "unreachable",
-            "status_code": None,
-            "healthy": False,
-            "error": "Tunnel request timed out",
-        }
-    except (ValueError, Exception) as exc:
-        error_str = str(exc).lower()
-        if any(
-            err in error_str
-            for err in [
-                "connection refused",
-                "econnrefused",
-                "could not resolve",
-                "nodename",
-            ]
-        ):
-            return {
-                "tunnel_status": "unreachable",
-                "status_code": None,
-                "healthy": False,
-                "error": f"Tunnel unreachable: {exc}",
-            }
-        return {
-            "tunnel_status": "unreachable",
-            "status_code": None,
-            "healthy": False,
-            "error": str(exc),
-        }

apps/api/tests/unit/test_tool_instances_legacy.py

@@ -411,8 +411,9 @@ class TestStartInstanceLegacyFallback:
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances._get_user")
@@ -423,8 +424,9 @@ class TestStartInstanceLegacyFallback:
         mock_get_user,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -440,7 +442,6 @@ class TestStartInstanceLegacyFallback:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
         mock_wait_container.return_value = {
             "success": True,
@@ -509,8 +510,9 @@ class TestStartInstanceLegacyFallback:
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances._get_user")
@@ -521,8 +523,9 @@ class TestStartInstanceLegacyFallback:
         mock_get_user,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -538,7 +541,6 @@ class TestStartInstanceLegacyFallback:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
         mock_wait_container.return_value = {
             "success": True,
@@ -606,8 +608,9 @@ class TestStartInstanceLegacyFallback:
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances._get_user")
@@ -618,8 +621,9 @@ class TestStartInstanceLegacyFallback:
         mock_get_user,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -635,7 +639,6 @@ class TestStartInstanceLegacyFallback:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
         mock_wait_container.return_value = {
             "success": True,
@@ -705,12 +708,14 @@ class TestStartInstanceSshPermissions:
     """SSH key mounts trigger permission fixes after container starts."""
 
     @patch("src.api.tool_instances.write_compose_file")
+    @patch("src.api.tool_instances.prepare_ssh_key_files")
     @patch("src.api.tool_instances.apply_ssh_permissions")
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._get_user")
     @patch("src.api.tool_instances._get_owned_project")
@@ -719,12 +724,14 @@ class TestStartInstanceSshPermissions:
         mock_get_project,
         mock_get_user,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
         mock_apply_ssh,
+        mock_prepare_ssh,
         mock_write_compose,
         mock_session,
         fake_user_id,
@@ -743,7 +750,6 @@ class TestStartInstanceSshPermissions:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
         mock_wait_container.return_value = {
             "success": True,
@@ -836,12 +842,14 @@ class TestStartInstanceSshPermissions:
         assert result["status"] == "running"
         mock_apply_ssh.assert_called_once_with("abc123", "/home/user/.ssh", "user")
 
+    @patch("src.api.tool_instances.prepare_ssh_key_files")
     @patch("src.api.tool_instances.apply_ssh_permissions")
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._get_user")
     @patch("src.api.tool_instances._get_owned_project")
@@ -850,12 +858,14 @@ class TestStartInstanceSshPermissions:
         mock_get_project,
         mock_get_user,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
         mock_apply_ssh,
+        mock_prepare_ssh,
         mock_session,
         fake_user_id,
         fake_project_id,
@@ -870,7 +880,6 @@ class TestStartInstanceSshPermissions:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
         mock_wait_container.return_value = {
             "success": True,
@@ -933,14 +942,15 @@ class TestStartInstanceSshPermissions:
         mock_session.get.side_effect = _get
 
         with patch("os.path.exists", return_value=True):
-            result = await start_instance(
-                project_id=fake_project_id,
-                repo_id=fake_repo_id,
-                instance_id=fake_instance_id,
-                data=None,
-                user_id=fake_user_id,
-                session=mock_session,
-            )
+            with patch("src.api.tool_instances._modify_compose_file"):
+                result = await start_instance(
+                    project_id=fake_project_id,
+                    repo_id=fake_repo_id,
+                    instance_id=fake_instance_id,
+                    data=None,
+                    user_id=fake_user_id,
+                    session=mock_session,
+                )
 
         assert result["status"] == "running"
         mock_apply_ssh.assert_called_once_with("abc123", "/root/.ssh", "root")
@@ -952,8 +962,9 @@ class TestStartInstanceManifestBranch:
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances.write_compose_file")
@@ -966,8 +977,9 @@ class TestStartInstanceManifestBranch:
         mock_write_compose,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -987,7 +999,6 @@ class TestStartInstanceManifestBranch:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
         mock_wait_container.return_value = {
             "success": True,

apps/web/src/components/session-card.tsx

@@ -229,13 +229,12 @@ export function SessionCard({
 								</button>
 							)}
 
-							{!isTerminalOnly && onRecreateTunnel && (
+							{hasTunnelError && onRecreateTunnel && (
 								<button
-									className="ghost-button small"
+									className="secondary-button small"
 									onClick={() => onRecreateTunnel(session)}
 									type="button"
 									disabled={isBusy}
-									title="Recreate Cloudflare tunnel"
 								>
 									<Icon name="refresh" size="sm" />
 									<span className="action-label">Tunnel</span>
@@ -324,7 +323,7 @@ export function SessionCard({
 				onClose={() => setShowActionSheet(false)}
 				title={session.display_name}
 				actions={[
-					...(isActive && !isTerminalOnly && onRecreateTunnel
+					...(isActive && hasTunnelError && onRecreateTunnel
 						? [
 								{
 									id: "tunnel",

apps/web/src/hooks/use-instance-actions.ts

@@ -1,187 +1,158 @@
 import { useState, useCallback } from "react";
 import {
-	stopInstance,
-	deleteInstance,
-	startInstance,
-	recreateInstanceTunnel,
+  stopInstance,
+  deleteInstance,
+  startInstance,
+  recreateInstanceTunnel,
 } from "../api/sessions";
 import type { Session } from "../api/sessions";
 
 interface UseInstanceActionsOptions {
-	onRefresh: () => Promise<void>;
+  onRefresh: () => Promise<void>;
 }
 
 interface UseInstanceActionsReturn {
-	loadingSessionId: string | null;
-	dirtyDeleteSession: Session | null;
-	dirtyDeleteFiles: string[];
-	handleOpen: (session: Session) => void;
-	handleStart: (session: Session) => Promise<void>;
-	handleStop: (session: Session) => Promise<void>;
-	handleDelete: (session: Session) => Promise<void>;
-	handleForceDelete: (session: Session) => Promise<void>;
-	handleRecreateTunnel: (session: Session) => Promise<void>;
-	clearDirtyDelete: () => void;
+  loadingSessionId: string | null;
+  dirtyDeleteSession: Session | null;
+  dirtyDeleteFiles: string[];
+  handleOpen: (session: Session) => void;
+  handleStart: (session: Session) => Promise<void>;
+  handleStop: (session: Session) => Promise<void>;
+  handleDelete: (session: Session) => Promise<void>;
+  handleForceDelete: (session: Session) => Promise<void>;
+  handleRecreateTunnel: (session: Session) => Promise<void>;
+  clearDirtyDelete: () => void;
 }
 
 export function useInstanceActions(
-	options: UseInstanceActionsOptions,
+  options: UseInstanceActionsOptions
 ): UseInstanceActionsReturn {
-	const { onRefresh } = options;
-	const [loadingSessionId, setLoadingSessionId] = useState<string | null>(null);
-	const [dirtyDeleteSession, setDirtyDeleteSession] = useState<Session | null>(
-		null,
-	);
-	const [dirtyDeleteFiles, setDirtyDeleteFiles] = useState<string[]>([]);
+  const { onRefresh } = options;
+  const [loadingSessionId, setLoadingSessionId] = useState<string | null>(null);
+  const [dirtyDeleteSession, setDirtyDeleteSession] = useState<Session | null>(null);
+  const [dirtyDeleteFiles, setDirtyDeleteFiles] = useState<string[]>([]);
 
-	const handleOpen = useCallback((session: Session) => {
-		if (session.url) {
-			window.open(session.url, "_blank", "noopener,noreferrer");
-			return;
-		}
-		if (session.tool_type_interfaces?.includes("terminal")) {
-			window.location.href = `/instances/${session.id}/terminal`;
-			return;
-		}
-		window.location.href = `/projects/${session.project_id}`;
-	}, []);
+  const handleOpen = useCallback((session: Session) => {
+    if (session.url) {
+      window.open(session.url, "_blank", "noopener,noreferrer");
+      return;
+    }
+    if (session.tool_type_interfaces?.includes("terminal")) {
+      window.location.href = `/instances/${session.id}/terminal`;
+      return;
+    }
+    window.location.href = `/projects/${session.project_id}`;
+  }, []);
 
-	const handleStart = useCallback(
-		async (session: Session) => {
-			if (loadingSessionId === session.id) return;
-			setLoadingSessionId(session.id);
-			try {
-				await startInstance(
-					session.project_id,
-					session.repository_id,
-					session.id,
-				);
-				await onRefresh();
-			} catch {
-				// ignore
-			} finally {
-				setLoadingSessionId(null);
-			}
-		},
-		[loadingSessionId, onRefresh],
-	);
+  const handleStart = useCallback(
+    async (session: Session) => {
+      if (loadingSessionId === session.id) return;
+      setLoadingSessionId(session.id);
+      try {
+        await startInstance(session.project_id, session.repository_id, session.id);
+        await onRefresh();
+      } catch {
+        // ignore
+      } finally {
+        setLoadingSessionId(null);
+      }
+    },
+    [loadingSessionId, onRefresh]
+  );
 
-	const handleStop = useCallback(
-		async (session: Session) => {
-			if (loadingSessionId === session.id) return;
-			setLoadingSessionId(session.id);
-			try {
-				await stopInstance(
-					session.project_id,
-					session.repository_id,
-					session.id,
-				);
-				await onRefresh();
-			} catch {
-				// ignore
-			} finally {
-				setLoadingSessionId(null);
-			}
-		},
-		[loadingSessionId, onRefresh],
-	);
+  const handleStop = useCallback(
+    async (session: Session) => {
+      if (loadingSessionId === session.id) return;
+      setLoadingSessionId(session.id);
+      try {
+        await stopInstance(session.project_id, session.repository_id, session.id);
+        await onRefresh();
+      } catch {
+        // ignore
+      } finally {
+        setLoadingSessionId(null);
+      }
+    },
+    [loadingSessionId, onRefresh]
+  );
 
-	const handleDelete = useCallback(
-		async (session: Session) => {
-			if (loadingSessionId === session.id) return;
-			setLoadingSessionId(session.id);
-			try {
-				await deleteInstance(
-					session.project_id,
-					session.repository_id,
-					session.id,
-				);
-				setDirtyDeleteSession(null);
-				setDirtyDeleteFiles([]);
-				await onRefresh();
-			} catch (error) {
-				const axiosError = error as {
-					response?: {
-						status?: number;
-						data?: { detail?: { changed_files?: string[] } };
-					};
-				};
-				if (axiosError.response?.status === 409) {
-					const detail = axiosError.response.data?.detail;
-					if (detail?.changed_files) {
-						setDirtyDeleteSession(session);
-						setDirtyDeleteFiles(detail.changed_files);
-						return;
-					}
-				}
-			} finally {
-				setLoadingSessionId(null);
-			}
-		},
-		[loadingSessionId, onRefresh],
-	);
+  const handleDelete = useCallback(
+    async (session: Session) => {
+      if (loadingSessionId === session.id) return;
+      setLoadingSessionId(session.id);
+      try {
+        await deleteInstance(session.project_id, session.repository_id, session.id);
+        setDirtyDeleteSession(null);
+        setDirtyDeleteFiles([]);
+        await onRefresh();
+      } catch (error) {
+        const axiosError = error as {
+          response?: { status?: number; data?: { detail?: { changed_files?: string[] } } };
+        };
+        if (axiosError.response?.status === 409) {
+          const detail = axiosError.response.data?.detail;
+          if (detail?.changed_files) {
+            setDirtyDeleteSession(session);
+            setDirtyDeleteFiles(detail.changed_files);
+            return;
+          }
+        }
+      } finally {
+        setLoadingSessionId(null);
+      }
+    },
+    [loadingSessionId, onRefresh]
+  );
 
-	const handleForceDelete = useCallback(
-		async (session: Session) => {
-			if (loadingSessionId === session.id) return;
-			setLoadingSessionId(session.id);
-			try {
-				await deleteInstance(
-					session.project_id,
-					session.repository_id,
-					session.id,
-					true,
-				);
-				setDirtyDeleteSession(null);
-				setDirtyDeleteFiles([]);
-				await onRefresh();
-			} catch {
-				// ignore
-			} finally {
-				setLoadingSessionId(null);
-			}
-		},
-		[loadingSessionId, onRefresh],
-	);
+  const handleForceDelete = useCallback(
+    async (session: Session) => {
+      if (loadingSessionId === session.id) return;
+      setLoadingSessionId(session.id);
+      try {
+        await deleteInstance(session.project_id, session.repository_id, session.id, true);
+        setDirtyDeleteSession(null);
+        setDirtyDeleteFiles([]);
+        await onRefresh();
+      } catch {
+        // ignore
+      } finally {
+        setLoadingSessionId(null);
+      }
+    },
+    [loadingSessionId, onRefresh]
+  );
 
-	const handleRecreateTunnel = useCallback(
-		async (session: Session) => {
-			if (loadingSessionId === session.id) return;
-			setLoadingSessionId(session.id);
-			try {
-				await recreateInstanceTunnel(
-					session.project_id,
-					session.repository_id,
-					session.id,
-				);
-				await onRefresh();
-			} catch (err) {
-				const message =
-					(err as { response?: { data?: { detail?: string } } })?.response?.data
-						?.detail || "Failed to recreate tunnel";
-				alert(message);
-			} finally {
-				setLoadingSessionId(null);
-			}
-		},
-		[loadingSessionId, onRefresh],
-	);
+  const handleRecreateTunnel = useCallback(
+    async (session: Session) => {
+      if (loadingSessionId === session.id) return;
+      setLoadingSessionId(session.id);
+      try {
+        await recreateInstanceTunnel(session.project_id, session.repository_id, session.id);
+        await onRefresh();
+      } catch {
+        // ignore
+      } finally {
+        setLoadingSessionId(null);
+      }
+    },
+    [loadingSessionId, onRefresh]
+  );
 
-	const clearDirtyDelete = useCallback(() => {
-		setDirtyDeleteSession(null);
-		setDirtyDeleteFiles([]);
-	}, []);
+  const clearDirtyDelete = useCallback(() => {
+    setDirtyDeleteSession(null);
+    setDirtyDeleteFiles([]);
+  }, []);
 
-	return {
-		loadingSessionId,
-		dirtyDeleteSession,
-		dirtyDeleteFiles,
-		handleOpen,
-		handleStart,
-		handleStop,
-		handleDelete,
-		handleForceDelete,
-		handleRecreateTunnel,
-		clearDirtyDelete,
-	};
+  return {
+    loadingSessionId,
+    dirtyDeleteSession,
+    dirtyDeleteFiles,
+    handleOpen,
+    handleStart,
+    handleStop,
+    handleDelete,
+    handleForceDelete,
+    handleRecreateTunnel,
+    clearDirtyDelete,
+  };
 }

docker-compose.traefik.yml

@@ -13,7 +13,11 @@ services:
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}"]
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}",
+        ]
       interval: 10s
       timeout: 5s
       retries: 5

docker-compose.yml

@@ -1,4 +1,4 @@
-version: '3.8'
+version: "3.8"
 
 services:
   # PostgreSQL Database
@@ -14,7 +14,11 @@ services:
     ports:
       - "5432:5432"
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}"]
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}",
+        ]
       interval: 10s
       timeout: 5s
       retries: 5