Phase 11: remote UX & network attach (0.11.0)

- Live remote-stack logs over a WebSocket proxied through the central app to
  the agent (/ws/agent-logs/{agent}/{stack}); agent gains a WS log endpoint.
- Deploy to a remote host from the UI: host selector in the New Stack editor
  and template dialog; templates instantiate onto an agent via the proxy.
- Network attach/detach: expandable inspect view per network with
  connect/disconnect + container picker; GET /{id}/containers, POST connect/disconnect.
- Remove dead pages/Placeholder.tsx.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/agent_app.py

@@ -16,7 +16,21 @@ from dataclasses import asdict
 
 import tempfile
 
-from fastapi import Depends, FastAPI, File, Form, Header, HTTPException, Query, Request, UploadFile
+import json
+
+from fastapi import (
+    Depends,
+    FastAPI,
+    File,
+    Form,
+    Header,
+    HTTPException,
+    Query,
+    Request,
+    UploadFile,
+    WebSocket,
+    WebSocketDisconnect,
+)
 from fastapi.responses import FileResponse, JSONResponse
 from pydantic import BaseModel
 
@@ -26,7 +40,7 @@ from services import backup_service, compose_service
 
 logger = logging.getLogger("stackpilot.agent")
 
-AGENT_VERSION = "0.10.0"
+AGENT_VERSION = "0.11.0"
 
 
 # --------------------------------------------------------------------------- #
@@ -274,6 +288,33 @@ async def restore_stack(
             os.unlink(tmp.name)
 
 
+@app.websocket("/agent/ws/logs/{stack_id}")
+async def ws_logs(websocket: WebSocket, stack_id: str, token: str | None = Query(default=None)):
+    """Stream `docker compose logs -f` to the central app (token via query param)."""
+    await websocket.accept()
+    expected = settings.AGENT_TOKEN
+    if not expected or token != expected:
+        await websocket.close(code=4401)
+        return
+    if not os.path.isdir(compose_service.stack_dir(stack_id)):
+        await websocket.send_text(json.dumps({"type": "error", "detail": "stack not found"}))
+        await websocket.close()
+        return
+    args = ["logs", "--no-color", "--tail", "200", "--timestamps", "-f"]
+    try:
+        async for line in compose_service.stream_compose(stack_id, args):
+            await websocket.send_text(
+                json.dumps({"type": "log", "stack_id": stack_id, "service": None, "line": line})
+            )
+    except WebSocketDisconnect:
+        pass
+    except Exception as exc:  # noqa: BLE001
+        try:
+            await websocket.send_text(json.dumps({"type": "error", "detail": str(exc)}))
+        except Exception:  # noqa: BLE001
+            pass
+
+
 @app.get("/agent/health")
 def health() -> dict:
     return {"status": "ok"}

backend/main.py

@@ -54,7 +54,7 @@ async def lifespan(app: FastAPI):
     schedule_task.cancel()
 
 
-app = FastAPI(title="StackPilot", version="0.10.0", lifespan=lifespan)
+app = FastAPI(title="StackPilot", version="0.11.0", lifespan=lifespan)
 
 app.add_middleware(
     CORSMiddleware,

backend/models/template.py

@@ -55,3 +55,4 @@ class TemplateSaveRequest(SQLModel):
 class TemplateInstantiateRequest(SQLModel):
     name: str  # new stack name
     values: dict[str, str] = {}
+    agent_id: int | None = None  # None = local host; otherwise deploy to a remote agent

backend/routers/networks.py

@@ -36,6 +36,12 @@ class NetworkCreate(BaseModel):
     attachable: bool = True
 
 
+class ContainerRef(BaseModel):
+    container: str
+    aliases: list[str] | None = None
+    force: bool = False
+
+
 @router.get("")
 def list_networks(_user: User = Depends(get_current_user)) -> list[dict]:
     return network_service.list_networks()
@@ -43,7 +49,58 @@ def list_networks(_user: User = Depends(get_current_user)) -> list[dict]:
 
 @router.get("/{network_id}")
 def inspect_network(network_id: str, _user: User = Depends(get_current_user)) -> dict:
-    return network_service.inspect_network(network_id)
+    try:
+        return network_service.inspect_network(network_id)
+    except DockerError as exc:
+        _map(exc)
+
+
+@router.get("/{network_id}/containers")
+def network_containers(
+    network_id: str, _user: User = Depends(get_current_user)
+) -> list[dict]:
+    try:
+        return network_service.connectable_containers(network_id)
+    except DockerError as exc:
+        _map(exc)
+
+
+@router.post("/{network_id}/connect")
+def connect_container(
+    network_id: str,
+    body: ContainerRef,
+    request: Request,
+    session: Session = Depends(get_session),
+    user: User = Depends(require_admin),
+) -> dict:
+    try:
+        network_service.connect_container(network_id, body.container, body.aliases)
+    except DockerError as exc:
+        _map(exc)
+    audit_service.record(
+        session, user=user.username, action="network.connect", target=network_id,
+        detail=body.container, ip=_ip(request),
+    )
+    return {"ok": True}
+
+
+@router.post("/{network_id}/disconnect")
+def disconnect_container(
+    network_id: str,
+    body: ContainerRef,
+    request: Request,
+    session: Session = Depends(get_session),
+    user: User = Depends(require_admin),
+) -> dict:
+    try:
+        network_service.disconnect_container(network_id, body.container, body.force)
+    except DockerError as exc:
+        _map(exc)
+    audit_service.record(
+        session, user=user.username, action="network.disconnect", target=network_id,
+        detail=body.container, ip=_ip(request),
+    )
+    return {"ok": True}
 
 
 @router.post("", status_code=201)

backend/routers/templates.py

@@ -8,10 +8,12 @@ from sqlmodel import Session
 
 from auth import get_current_user, require_admin
 from database import get_session
+from models.agent import Agent
 from models.stack import Stack
 from models.template import TemplateInstantiateRequest, TemplateSaveRequest
 from models.user import User
-from services import audit_service, compose_service, template_service
+from services import agent_service, audit_service, compose_service, template_service
+from services.agent_service import AgentError
 
 router = APIRouter(prefix="/api/templates", tags=["templates"])
 
@@ -72,7 +74,7 @@ def delete_template(
 
 
 @router.post("/{template_id}/instantiate", status_code=201)
-def instantiate(
+async def instantiate(
     template_id: str,
     body: TemplateInstantiateRequest,
     request: Request,
@@ -83,11 +85,32 @@ def instantiate(
     if not tpl:
         raise HTTPException(status_code=404, detail="Template not found")
 
+    rendered = template_service.render(tpl["yaml"], body.values)
+
+    if body.agent_id is not None:
+        agent = session.get(Agent, body.agent_id)
+        if not agent:
+            raise HTTPException(status_code=404, detail=f"Agent {body.agent_id} not found")
+        try:
+            result = await agent_service.call(
+                session, agent, "POST", "/agent/stacks",
+                json={"name": body.name, "yaml": rendered, "env": None},
+            )
+        except AgentError as exc:
+            raise HTTPException(
+                status_code=exc.status if exc.status >= 400 else 502,
+                detail={"error": exc.error, "detail": exc.detail},
+            )
+        audit_service.record(
+            session, user=user.username, action="template.instantiate",
+            target=f"{agent.name}/{result.get('id')}", detail=template_id, ip=_ip(request),
+        )
+        return {"id": result.get("id"), "name": body.name, "agent_id": agent.id}
+
     stack_id = compose_service.slugify(body.name)
     if session.get(Stack, stack_id) or os.path.isdir(compose_service.stack_dir(stack_id)):
         raise HTTPException(status_code=409, detail=f"Stack '{stack_id}' already exists")
 
-    rendered = template_service.render(tpl["yaml"], body.values)
     compose_service.write_compose(stack_id, rendered)
     stack = Stack(id=stack_id, name=body.name, description=tpl.get("description"))
     session.add(stack)
@@ -96,4 +119,4 @@ def instantiate(
         session, user=user.username, action="template.instantiate",
         target=stack_id, detail=template_id, ip=_ip(request),
     )
-    return {"id": stack_id, "name": body.name}
+    return {"id": stack_id, "name": body.name, "agent_id": None}

backend/routers/ws.py

@@ -4,10 +4,16 @@ from __future__ import annotations
 import asyncio
 import json
 
+import contextlib
+
+import websockets
 from fastapi import APIRouter, Query, WebSocket, WebSocketDisconnect
 from jose import JWTError
+from sqlmodel import Session
 
 from auth import decode_token
+from database import engine
+from models.agent import Agent
 from services import compose_service
 
 router = APIRouter(tags=["ws"])
@@ -82,6 +88,47 @@ async def ws_service_logs(
         pass
 
 
+@router.websocket("/ws/agent-logs/{agent_id}/{stack_id}")
+async def ws_agent_logs(
+    websocket: WebSocket,
+    agent_id: int,
+    stack_id: str,
+    token: str | None = Query(default=None),
+):
+    """Proxy live compose logs from a remote agent through to the browser."""
+    await websocket.accept()
+    if not await _authorize(websocket, token):
+        return
+
+    with Session(engine) as session:
+        agent = session.get(Agent, agent_id)
+    if not agent:
+        await websocket.send_text(json.dumps({"type": "error", "detail": "agent not found"}))
+        await websocket.close()
+        return
+
+    base = agent.url.rstrip("/")
+    ws_url = ("wss://" + base[8:] if base.startswith("https://")
+              else "ws://" + base[7:] if base.startswith("http://")
+              else "ws://" + base)
+    ws_url += f"/agent/ws/logs/{stack_id}?token={agent.token}"
+
+    try:
+        async with websockets.connect(ws_url, open_timeout=10, ping_interval=20) as upstream:
+            async for message in upstream:
+                await websocket.send_text(
+                    message if isinstance(message, str) else message.decode("utf-8", "replace")
+                )
+    except WebSocketDisconnect:
+        pass
+    except Exception as exc:  # noqa: BLE001
+        with contextlib.suppress(Exception):
+            await websocket.send_text(json.dumps({"type": "error", "detail": str(exc)}))
+    finally:
+        with contextlib.suppress(Exception):
+            await websocket.close()
+
+
 @router.websocket("/ws/events")
 async def ws_events(
     websocket: WebSocket,

backend/services/network_service.py

@@ -86,6 +86,43 @@ def create_network(spec: dict) -> dict:
     return _summary(net)
 
 
+def connectable_containers(network_id: str) -> list[dict]:
+    """All containers on the host, flagged whether already on this network."""
+    client = get_client()
+    net = safe_call(client.networks.get, network_id)
+    net.reload()
+    connected = set((net.attrs.get("Containers") or {}).keys())
+    out = []
+    for c in safe_call(client.containers.list, all=True):
+        labels = c.labels or {}
+        out.append(
+            {
+                "id": c.id[:12],
+                "name": c.name,
+                "state": c.status,
+                "stack": labels.get(COMPOSE_PROJECT_LABEL),
+                "connected": c.id in connected,
+            }
+        )
+    return sorted(out, key=lambda x: x["name"])
+
+
+def connect_container(network_id: str, container: str, aliases: Optional[list[str]] = None) -> None:
+    if not (container or "").strip():
+        raise DockerError("invalid_request", "Container is required")
+    client = get_client()
+    net = safe_call(client.networks.get, network_id)
+    safe_call(net.connect, container, aliases=aliases or None)
+
+
+def disconnect_container(network_id: str, container: str, force: bool = False) -> None:
+    if not (container or "").strip():
+        raise DockerError("invalid_request", "Container is required")
+    client = get_client()
+    net = safe_call(client.networks.get, network_id)
+    safe_call(net.disconnect, container, force=force)
+
+
 def delete_network(network_id: str) -> None:
     client = get_client()
     net = safe_call(client.networks.get, network_id)