Remove the remote-host (agent) integration (0.48.0)

StackPilot now manages exactly one Docker host: the one it runs on. The
stackpilot-agent sidecar and everything that proxied to it are gone — 4721
lines deleted against 657 added.

Deleted outright: agent/ (image, compose, env), agent_app.py, models/agent.py,
routers/agents.py (1200 lines), services/agent_service.py, the agent API client,
RemoteStackDetail, the host components and AgentStacksSection. That removes 57
API routes and the three /ws/agent-* proxies.

Threaded out everywhere else, which was the bulk of the work. Every API module
carried an optional agentId that switched the base path; every page that listed
Docker objects rendered one section per host behind a HostHeader; Files had a
host switcher; the New Stack editor and the template dialog had host selectors;
schedules, auto-update policies and stack summaries carried agent_id. All of it
is gone, and the typechecker drove the sweep — 85 files touched, tsc and the
build clean.

Two things the removal exposed as dead weight rather than merely unused:

compose_service kept an in-process busy set purely because the agent needed a
lock and has no database. With the agent gone that was a second source of truth
next to the real DB lock, so it is deleted; compute_status now reports only what
the containers say and the two callers that want "updating" overlay the lock.
StacksTable's linkBase prop only ever existed to point at /hosts/{id}/stacks.

The dashboard's "Hosts 1/1 online" KPI can no longer say anything else, so the
tile and the KPIs behind it are gone and the row is five wide.

Upgrading matters here. An existing install still has an agent table holding
each remote host's URL and bearer token — full Docker control of that host,
sitting in the database with nothing left to use it. _drop_removed_schema drops
it on first start, and drops the agent_id columns where the SQLite build
supports DROP COLUMN. Each statement runs in its own transaction on purpose: a
failed DDL poisons the transaction it is in, so sharing one would let an
unsupported column drop take the table drop down with it. test_agent_removal
covers both branches plus the fresh-install and idempotent cases, and an
end-to-end run against a seeded pre-0.48 database confirms the table is gone and
every /api/agents route answers 404.

Docstrings that justified a design by "shared with the agent, which has no
database" were rewritten rather than left lying: update_service's persistence
callback and image_status_store are still the right split (registry logic stays
testable without a database), but for that reason now, not the old one. The
README's multi-host sections are removed and an upgrade note explains what to do
with running agent containers; ROADMAP keeps its history behind a note saying
the feature it describes no longer exists.

CI no longer builds or pushes stackpilot-agent.

735 tests pass, ruff and tsc clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dk43rmEeRfYi5wsLDbmfyG

backend/routers/dashboard.py

@@ -24,7 +24,7 @@ async def fleet(
     _user: User = Depends(get_current_user),
 ) -> dict:
     """Fleet-wide 'needs attention' list, KPIs and per-host rollup across the
-    local host and every agent — the data behind the operator cockpit."""
+    the host — the data behind the operator cockpit."""
     try:
         return await dashboard_service.compute_fleet(session, refresh=refresh)
     except Exception as exc:  # noqa: BLE001 — surface the real cause for diagnosis

backend/routers/schedules.py

@@ -6,7 +6,6 @@ from sqlmodel import Session, select
 
 from auth import require_admin
 from database import get_session
-from models.agent import Agent
 from models.backup_destination import BackupDestination
 from models.backup_schedule import (
     FREQUENCIES,
@@ -28,14 +27,11 @@ def _ip(request: Request) -> str:
 
 def _to_read(session: Session, s: BackupSchedule) -> ScheduleRead:
     dest = session.get(BackupDestination, s.destination_id)
-    agent = session.get(Agent, s.agent_id) if s.agent_id is not None else None
     return ScheduleRead(
         id=s.id,
         stack_id=s.stack_id,
         destination_id=s.destination_id,
         destination_name=dest.name if dest else None,
-        agent_id=s.agent_id,
-        agent_name=agent.name if agent else None,
         frequency=s.frequency,
         hour=s.hour,
         minute=s.minute,
@@ -63,11 +59,7 @@ def _validate(session: Session, schedule: BackupSchedule) -> None:
         raise HTTPException(status_code=400, detail=f"Unknown frequency '{schedule.frequency}'")
     if not session.get(BackupDestination, schedule.destination_id):
         raise HTTPException(status_code=404, detail=f"Destination {schedule.destination_id} not found")
-    if schedule.agent_id is not None:
-        # Remote stack: validate the agent exists; the stack is checked at run time.
-        if not session.get(Agent, schedule.agent_id):
-            raise HTTPException(status_code=404, detail=f"Agent {schedule.agent_id} not found")
-    elif not session.get(Stack, schedule.stack_id):
+    if not session.get(Stack, schedule.stack_id):
         raise HTTPException(status_code=404, detail=f"Stack '{schedule.stack_id}' not found")
 
 

backend/routers/secrets.py

@@ -51,7 +51,6 @@ def _guard(fn, *args, **kwargs):
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
 
-# --- These functions are shared verbatim by the agent (see agent_app.py). ---
 
 
 def list_secrets(stack_id: str) -> list[dict]:

backend/routers/stacks.py

@@ -178,6 +178,9 @@ def get_stack(
     except DockerError:
         containers = []
         status = "unknown"
+    # An operation in flight outranks whatever the containers currently say.
+    if stack_lock_service.is_busy(session, stack_id):
+        status = "updating"
     return {
         "id": stack.id,
         "name": stack.name,
@@ -451,7 +454,7 @@ def get_auto_update(
     _user: User = Depends(get_current_user),
 ) -> dict:
     policy = auto_update_service.get_policy(session, stack_id)
-    return auto_update_service.to_read(session, policy, stack_id)
+    return auto_update_service.to_read(policy, stack_id)
 
 
 @router.put("/{stack_id}/auto-update", response_model=AutoUpdateRead)
@@ -468,7 +471,7 @@ def set_auto_update(
         target=stack_id, detail=f"enabled={body.enabled} redeploy={body.redeploy}",
         ip=_client_ip(request),
     )
-    return auto_update_service.to_read(session, policy, stack_id)
+    return auto_update_service.to_read(policy, stack_id)
 
 
 @router.post("/{stack_id}/auto-update/run", response_model=AutoUpdateRead)
@@ -482,4 +485,4 @@ async def run_auto_update(
         raise HTTPException(status_code=404, detail="No auto-update policy for this stack")
     await auto_update_service.run_policy(session, policy)
     session.refresh(policy)
-    return auto_update_service.to_read(session, policy, stack_id)
+    return auto_update_service.to_read(policy, stack_id)

backend/routers/templates.py

@@ -12,7 +12,6 @@ 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 (
     TemplateFromStackRequest,
@@ -20,8 +19,7 @@ from models.template import (
     TemplateSaveRequest,
 )
 from models.user import User
-from services import agent_service, audit_service, compose_service, template_service
-from services.agent_service import AgentError
+from services import audit_service, compose_service, template_service
 
 router = APIRouter(prefix="/api/templates", tags=["templates"])
 
@@ -103,7 +101,7 @@ def delete_template(
 
 
 @router.post("/{template_id}/instantiate", status_code=201)
-async def instantiate(
+def instantiate(
     template_id: str,
     body: TemplateInstantiateRequest,
     request: Request,
@@ -114,28 +112,7 @@ async def instantiate(
     if not tpl:
         raise HTTPException(status_code=404, detail="Template not found")
 
-    # Remote host: agents don't share our filesystem, so ship compose + env.
-    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": tpl["compose"], "env": tpl["env"] or None},
-            )
-        except AgentError as exc:
-            raise HTTPException(
-                status_code=exc.status if exc.status >= 400 else 502,
-                detail={"error": exc.error, "detail": exc.detail},
-            ) from exc
-        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}
-
-    # Local host: copy the whole template folder into a new stack.
+    # Copy the whole template folder into a new stack.
     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")
@@ -156,4 +133,4 @@ async 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, "agent_id": None}
+    return {"id": stack_id, "name": body.name}

backend/routers/ws.py

@@ -4,18 +4,15 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
-import urllib.parse
 
 import contextlib
 
-import websockets
 from fastapi import APIRouter, Query, WebSocket, WebSocketDisconnect
 from jose import JWTError
 from sqlmodel import Session
 
 from auth import decode_token, resolve_token_user
 from database import engine
-from models.agent import Agent
 from models.setting import EVENT_PULL_FAILED, EVENT_STACK_ERROR, EVENT_STACK_START
 from services import (
     audit_service,
@@ -158,7 +155,6 @@ async def ws_deploy(
             await websocket.send_text(json.dumps({"type": "error", "detail": str(exc)}))
             await websocket.close(code=4409)
         return
-    compose_service.mark_busy(stack_id)
     try:
         async for kind, payload in compose_service.stream_up(stack_id):
             if kind == "log":
@@ -174,7 +170,6 @@ async def ws_deploy(
         with contextlib.suppress(Exception):
             await websocket.send_text(json.dumps({"type": "error", "detail": str(exc)}))
     finally:
-        compose_service.clear_busy(stack_id)
         with contextlib.suppress(Exception):
             stack_lock_service.release(lock_session, stack_id)
         lock_session.close()
@@ -203,78 +198,6 @@ async def ws_deploy(
             await websocket.close()
 
 
-@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)
-    # URL-encode the token: agent tokens may contain base64 chars (+ / =) that
-    # would otherwise be mangled in the query string and rejected as 4401.
-    ws_url += f"/agent/ws/logs/{stack_id}?token={urllib.parse.quote(agent.token, safe='')}"
-
-    async def _err(detail: str) -> None:
-        with contextlib.suppress(Exception):
-            await websocket.send_text(json.dumps({"type": "error", "detail": detail}))
-
-    # Connect to the agent. Surface connection problems (agent down, wrong URL,
-    # an outdated agent that lacks /agent/ws/logs, TLS issues) instead of
-    # silently dropping the socket.
-    try:
-        upstream = await websockets.connect(ws_url, open_timeout=10, ping_interval=20)
-    except websockets.InvalidStatus as exc:
-        code = getattr(getattr(exc, "response", None), "status_code", None)
-        hint = " — the agent may be running an old version without live-log support; update it." if code == 404 else ""
-        logger.warning("Agent log proxy: handshake to %s failed (%s)", agent.name, code)
-        await _err(f"Agent '{agent.name}' rejected the log stream (HTTP {code}){hint}")
-        with contextlib.suppress(Exception):
-            await websocket.close()
-        return
-    except Exception as exc:  # noqa: BLE001
-        logger.warning("Agent log proxy: cannot reach %s at %s: %s", agent.name, agent.url, exc)
-        await _err(f"Could not connect to agent '{agent.name}' at {agent.url}: {exc}")
-        with contextlib.suppress(Exception):
-            await websocket.close()
-        return
-
-    try:
-        async for message in upstream:
-            await websocket.send_text(
-                message if isinstance(message, str) else message.decode("utf-8", "replace")
-            )
-    except WebSocketDisconnect:
-        pass
-    except websockets.ConnectionClosed as exc:
-        # Abnormal upstream close (e.g. 4401 bad token, or agent-side error).
-        if exc.code not in (1000, 1001):
-            await _err(f"Agent log stream closed unexpectedly (code {exc.code}).")
-    except Exception as exc:  # noqa: BLE001
-        logger.warning("Agent log proxy: stream error from %s: %s", agent.name, exc)
-        await _err(str(exc))
-    finally:
-        with contextlib.suppress(Exception):
-            await upstream.close()
-        with contextlib.suppress(Exception):
-            await websocket.close()
-
-
 @router.websocket("/ws/update/{stack_id}")
 async def ws_update(
     websocket: WebSocket,
@@ -300,7 +223,6 @@ async def ws_update(
             await websocket.send_text(json.dumps({"type": "error", "detail": str(exc)}))
             await websocket.close(code=4409)
         return
-    compose_service.mark_busy(stack_id)
     try:
         async for kind, payload in compose_service.stream_update(stack_id):
             if kind == "log":
@@ -315,7 +237,6 @@ async def ws_update(
         with contextlib.suppress(Exception):
             await websocket.send_text(json.dumps({"type": "error", "detail": str(exc)}))
     finally:
-        compose_service.clear_busy(stack_id)
         with contextlib.suppress(Exception):
             stack_lock_service.release(lock_session, stack_id)
         lock_session.close()
@@ -347,85 +268,6 @@ async def ws_update(
         update_service.refresh_stack_local(stack_id)
 
 
-@router.websocket("/ws/agent-deploy/{agent_id}/{stack_id}")
-async def ws_agent_deploy(
-    websocket: WebSocket,
-    agent_id: int,
-    stack_id: str,
-    token: str | None = Query(default=None),
-):
-    """Proxy a remote agent's `compose up` deploy stream through to the browser,
-    then record the same audit entry as the REST agent lifecycle endpoint."""
-    await websocket.accept()
-    if not await _authorize(websocket, token):
-        return
-    username = decode_token(token, "access").get("sub", "unknown") if token else "unknown"
-
-    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/deploy/{stack_id}?token={urllib.parse.quote(agent.token, safe='')}"
-
-    async def _err(detail: str) -> None:
-        with contextlib.suppress(Exception):
-            await websocket.send_text(json.dumps({"type": "error", "detail": detail}))
-
-    try:
-        upstream = await websockets.connect(ws_url, open_timeout=10, ping_interval=20)
-    except websockets.InvalidStatus as exc:
-        code = getattr(getattr(exc, "response", None), "status_code", None)
-        hint = " — the agent may be running an old version without deploy-console support; update it." if code == 404 else ""
-        logger.warning("Agent deploy proxy: handshake to %s failed (%s)", agent.name, code)
-        await _err(f"Agent '{agent.name}' rejected the deploy stream (HTTP {code}){hint}")
-        with contextlib.suppress(Exception):
-            await websocket.close()
-        return
-    except Exception as exc:  # noqa: BLE001
-        logger.warning("Agent deploy proxy: cannot reach %s at %s: %s", agent.name, agent.url, exc)
-        await _err(f"Could not connect to agent '{agent.name}' at {agent.url}: {exc}")
-        with contextlib.suppress(Exception):
-            await websocket.close()
-        return
-
-    rc: int | None = None
-    try:
-        async for message in upstream:
-            text = message if isinstance(message, str) else message.decode("utf-8", "replace")
-            with contextlib.suppress(Exception):
-                msg = json.loads(text)
-                if msg.get("type") == "done":
-                    rc = msg.get("returncode")
-            await websocket.send_text(text)
-    except WebSocketDisconnect:
-        pass
-    except websockets.ConnectionClosed as exc:
-        if exc.code not in (1000, 1001):
-            await _err(f"Agent deploy stream closed unexpectedly (code {exc.code}).")
-    except Exception as exc:  # noqa: BLE001
-        logger.warning("Agent deploy proxy: stream error from %s: %s", agent.name, exc)
-        await _err(str(exc))
-    finally:
-        with contextlib.suppress(Exception):
-            await upstream.close()
-        with contextlib.suppress(Exception):
-            await websocket.close()
-
-    with contextlib.suppress(Exception):
-        with Session(engine) as session:
-            audit_service.record(
-                session, user=username, action="agent.stack.start",
-                target=f"{agent.name}/{stack_id}", detail=f"rc={rc} (deploy console)", ip="ws",
-            )
-
-
 @router.websocket("/ws/events")
 async def ws_events(
     websocket: WebSocket,
@@ -514,91 +356,3 @@ async def ws_exec(
             await websocket.close()
 
 
-@router.websocket("/ws/agent-exec/{agent_id}/{container_id}")
-async def ws_agent_exec(
-    websocket: WebSocket,
-    agent_id: int,
-    container_id: str,
-    token: str | None = Query(default=None),
-    cmd: str | None = Query(default=None),
-):
-    """Proxy an interactive exec session to a remote agent (admin only).
-
-    Unlike the log/deploy proxies this forwards in BOTH directions so keystrokes
-    reach the container and its output streams back."""
-    await websocket.accept()
-    if not await _authorize_admin(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/exec/{container_id}?token={urllib.parse.quote(agent.token, safe='')}"
-    if cmd:
-        ws_url += f"&cmd={urllib.parse.quote(cmd, safe='')}"
-
-    async def _err(detail: str) -> None:
-        with contextlib.suppress(Exception):
-            await websocket.send_text(json.dumps({"type": "error", "detail": detail}))
-
-    try:
-        upstream = await websockets.connect(ws_url, open_timeout=10, ping_interval=20)
-    except websockets.InvalidStatus as exc:
-        code = getattr(getattr(exc, "response", None), "status_code", None)
-        hint = " — the agent may be running an old version without terminal support; update it." if code == 404 else ""
-        logger.warning("Agent exec proxy: handshake to %s failed (%s)", agent.name, code)
-        await _err(f"Agent '{agent.name}' rejected the terminal (HTTP {code}){hint}")
-        with contextlib.suppress(Exception):
-            await websocket.close()
-        return
-    except Exception as exc:  # noqa: BLE001
-        logger.warning("Agent exec proxy: cannot reach %s at %s: %s", agent.name, agent.url, exc)
-        await _err(f"Could not connect to agent '{agent.name}' at {agent.url}: {exc}")
-        with contextlib.suppress(Exception):
-            await websocket.close()
-        return
-
-    with contextlib.suppress(Exception):
-        with Session(engine) as session:
-            username = decode_token(token, "access").get("sub", "unknown") if token else "unknown"
-            audit_service.record(
-                session, user=username, action="agent.container.exec",
-                target=f"{agent.name}/{container_id[:12]}", ip="ws",
-            )
-
-    async def browser_to_agent() -> None:
-        try:
-            while True:
-                msg = await websocket.receive_text()
-                await upstream.send(msg)
-        except (WebSocketDisconnect, websockets.ConnectionClosed):
-            pass
-
-    async def agent_to_browser() -> None:
-        try:
-            async for message in upstream:
-                await websocket.send_text(
-                    message if isinstance(message, str) else message.decode("utf-8", "replace")
-                )
-        except (WebSocketDisconnect, websockets.ConnectionClosed):
-            pass
-
-    b2a = asyncio.create_task(browser_to_agent())
-    a2b = asyncio.create_task(agent_to_browser())
-    done, pending = await asyncio.wait({b2a, a2b}, return_when=asyncio.FIRST_COMPLETED)
-    for task in pending:
-        task.cancel()
-    with contextlib.suppress(Exception):
-        await asyncio.gather(*pending, return_exceptions=True)
-    with contextlib.suppress(Exception):
-        await upstream.close()
-    with contextlib.suppress(Exception):
-        await websocket.close()