fix(compose): get the v2 stack working as a 4-service local dev loop

api/Dockerfile

@@ -61,9 +61,11 @@ USER streamspace
 # Expose API port
 EXPOSE 8000
 
-# Health check
+# Health check. NOTE: BusyBox wget's --spider sends HEAD, which gin's
+# router answers with 404 because the /health route is registered for
+# GET only. Use -O /dev/null to force GET and discard the body.
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-    CMD wget --no-verbose --tries=1 --spider http://localhost:8000/health || exit 1
+    CMD wget -q -O /dev/null http://localhost:8000/health || exit 1
 
 # Environment variables with defaults
 ENV API_PORT=8000 \

api/internal/handlers/sessiontemplates.go

@@ -620,7 +620,7 @@ func (h *SessionTemplatesHandler) UseSessionTemplate(c *gin.Context) {
 		PersistentHome: true,
 	}
 
-	// Add template configuration for Docker controller
+	// Add template configuration for the Docker agent (v2; was "Docker controller" pre-v2 rename).
 	if k8sTemplate != nil {
 		// Selkies-GStreamer defaults to port 8080. Templates still carry a
 		// legacy VNC.Port field for backwards-compat with old fixtures; honor

docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3.9'
-
 services:
   # PostgreSQL database
   postgres:
@@ -10,7 +8,9 @@ services:
       POSTGRES_USER: streamspace
       POSTGRES_PASSWORD: streamspace
     ports:
-      - "5432:5432"
+      # Host 5433 → container 5432 to avoid clashing with a host Postgres on 5432.
+      # Internally, services on the streamspace network still reach it on 5432.
+      - "5433:5432"
     volumes:
       - postgres-data:/var/lib/postgresql/data
     healthcheck:
@@ -71,14 +71,29 @@ services:
       API_PORT: 8000
       GIN_MODE: debug
 
-      # JWT configuration
-      JWT_SECRET: dev-secret-change-in-production
+      # JWT configuration. Must be >=32 chars per api/internal/auth check.
+      JWT_SECRET: dev-jwt-secret-change-in-production-please-use-a-real-one
+
+      # Dev admin credentials — bypasses the first-run setup wizard so the
+      # login form (admin/admin123) works immediately. Override or remove
+      # for any non-local deployment.
+      ADMIN_PASSWORD: admin123
+
+      # Agent bootstrap key — must match the AGENT_API_KEY passed to the
+      # docker-agent service below. The agent self-registers on first
+      # connect when its API key matches this bootstrap key. Format must
+      # be 64 hex characters (validated by api/internal/auth.ValidateAPIKeyFormat).
+      AGENT_BOOTSTRAP_KEY: deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
 
       # NATS configuration
       NATS_URL: nats://nats:4222
       NATS_USER: ""
       NATS_PASSWORD: ""
-      PLATFORM: kubernetes
+      # Docker-platform mode for the local compose stack — k8sClient stays
+      # nil (the API tolerates this; see api/cmd/main.go around the k8s
+      # NewClient call). For kubernetes, mount a kubeconfig and set this
+      # to "kubernetes".
+      PLATFORM: docker
 
       # Sync configuration
       SYNC_INTERVAL: 1h
@@ -92,37 +107,79 @@ services:
       # - ~/.kube:/root/.kube:ro
       - /tmp/streamspace-repos:/tmp/streamspace-repos
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8000/health"]
+      # `wget --spider` sends HEAD; gin's /health route only answers GET.
+      # Use -O /dev/null to force a GET that succeeds with the registered route.
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8000/health"]
       interval: 30s
       timeout: 3s
       retries: 3
     networks:
       - streamspace
     restart: unless-stopped
 
-  # StreamSpace Docker Controller (for Docker platform support)
-  docker-controller:
+  # StreamSpace Docker Agent (v2 architecture).
+  #
+  # NOTE: The Docker agent fell behind during k8s-agent development — its
+  # session lifecycle handlers may be incomplete relative to k8s-agent.
+  # This service is wired here so the v2 control-plane → agent topology
+  # can boot end-to-end, but launching real Docker-backed sessions through
+  # the agent is not guaranteed to fully work yet. Use the k8s deployment
+  # path (manifests/) for verified end-to-end streaming until the docker
+  # agent catches up.
+  #
+  # Self-registers on first connect using AGENT_BOOTSTRAP_KEY (set on the
+  # API service above) — no manual provisioning needed for dev.
+  docker-agent:
     build:
-      context: ./docker-controller
+      context: ./agents/docker-agent
       dockerfile: Dockerfile
-    container_name: streamspace-docker-controller
+    container_name: streamspace-docker-agent
     depends_on:
-      nats:
+      api:
         condition: service_healthy
     environment:
-      NATS_URL: nats://nats:4222
-      NATS_USER: ""
-      NATS_PASSWORD: ""
-      CONTROLLER_ID: streamspace-docker-controller-1
+      AGENT_ID: docker-agent-local
+      CONTROL_PLANE_URL: ws://api:8000/api/v1/agents/connect
+      AGENT_API_KEY: deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
+      REGION: local
       DOCKER_NETWORK: streamspace
+      LEADER_ELECTION_BACKEND: file
+    # Agent needs to manage Docker containers on the host. The :ro flag
+    # from the previous docker-controller config wouldn't allow create/start.
     volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /var/run/docker.sock:/var/run/docker.sock
     networks:
       - streamspace
     profiles:
       - docker
     restart: unless-stopped
 
+  # StreamSpace Web UI. Nginx serves the built React bundle and proxies
+  # /api/ + /ws/ to the api service (config in ui/nginx.conf). Visit
+  # http://localhost:3000 in the browser.
+  ui:
+    build:
+      context: ./ui
+      dockerfile: Dockerfile
+      args:
+        VERSION: ${VERSION:-dev}
+        COMMIT: ${COMMIT:-local}
+        BUILD_DATE: ${BUILD_DATE}
+    container_name: streamspace-ui
+    depends_on:
+      api:
+        condition: service_healthy
+    ports:
+      - "3000:80"
+    networks:
+      - streamspace
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+    restart: unless-stopped
+
   # pgAdmin for database management (optional, for development)
   pgadmin:
     image: dpage/pgadmin4:latest

scripts/README-V2.md

@@ -45,7 +45,7 @@ These scripts reference v1.0 architecture (CRDs, controller) and need updates:
 | `local-teardown.sh` | Teardown local env | ⚠️ Minor updates needed |
 | `local-port-forward.sh` | Port-forward services | ✅ Mostly works, add agent logs |
 | `local-stop-port-forward.sh` | Stop port-forwards | ✅ Works as-is |
-| `build-docker-controller.sh` | Build controller image | ⚠️ Rename to build K8s Agent |
+| `local-build.sh docker-agent` | Build Docker agent image | ✅ Replaced legacy `build-docker-controller.sh` |
 | `docker-dev.sh` | Docker dev environment | ⚠️ Update for Control Plane + Agent |
 | `docker-dev-stop.sh` | Stop Docker dev | ✅ Works as-is |
 | `test-nats.sh` | Test NATS connectivity | ⚠️ Update for agent WebSocket |

scripts/README.md

@@ -51,7 +51,7 @@ For the new event-driven multi-platform architecture, use these scripts:
 # Start development environment (PostgreSQL, NATS)
 ./scripts/docker-dev.sh
 
-# Start with Docker controller
+# Start with Docker agent
 ./scripts/docker-dev.sh --with-docker
 
 # Start with all services (including monitoring)
@@ -73,7 +73,7 @@ Starts the complete development environment using Docker Compose with NATS and P
 ```bash
 ./scripts/docker-dev.sh              # Core services only
 ./scripts/docker-dev.sh --with-api   # Include API service
-./scripts/docker-dev.sh --with-docker # Include Docker controller
+./scripts/docker-dev.sh --with-docker # Include Docker agent
 ./scripts/docker-dev.sh --all        # All services and profiles
 ./scripts/docker-dev.sh --logs       # Start and follow logs
 ```
@@ -86,7 +86,7 @@ Starts the complete development environment using Docker Compose with NATS and P
 **Optional Services:**
 
 - API backend (--with-api)
-- Docker controller (--with-docker)
+- Docker agent (--with-docker)
 - pgAdmin (--with-dev)
 - Prometheus/Grafana (--with-monitor)
 
@@ -101,17 +101,6 @@ Stops the Docker Compose development environment.
 ./scripts/docker-dev-stop.sh --clean   # Stop and remove volumes
 ```
 
-### build-docker-controller.sh
-
-Builds the Docker platform controller for the event-driven architecture.
-
-**Usage:**
-
-```bash
-./scripts/build-docker-controller.sh           # Build Docker image
-./scripts/build-docker-controller.sh --binary  # Build Go binary only
-```
-
 ### test-nats.sh
 
 Tests NATS connectivity and can publish/subscribe to test events.