feat: Docker and helm charts

Session.Close now closing its own accepted conn (from the prior fix wave)
made net.ErrClosed on the guacd-side reader indistinguishable from a real
remote failure, so a normal browser-tab close could race the handler's
defer and intermittently log console.proxy_failed on a healthy session.
Add a closing flag, set before Close's sync.Once body actually tears
anything down, that setReason respects -- a deliberate local teardown can
no longer produce or race in a failure reason, while Close's own explicit
reason argument still wins normally.

.gitignore

@@ -3,6 +3,7 @@ dist
 build
 .env
 .env.bck
+.env.live
 docs/*
 !docs/superpowers/
 .superpowers
@@ -12,4 +13,5 @@ installer/nssm.zip
 installer/checksums-msi.txt
 .next
 *.tsbuildinfo
-graphify-out
+graphify-out
+docker-compose.live.yml

admin/internal/lifecycle/lifecycle.go

@@ -77,6 +77,16 @@ func Run(ctx context.Context) error {
 			}
 		}
 
+		if lic.ExpiresAt.Add(reapAfter).Before(now) {
+			if _, err := db.Admin("admin_instances").DeleteOne(ctx, bson.M{"instance_id": inst.InstanceID}); err != nil {
+				log.Printf("lifecycle: delete instance %s: %v", inst.InstanceID, err)
+			}
+
+			if _, err := db.Admin("licenses").DeleteMany(ctx, bson.M{"instance_id": inst.InstanceID}); err != nil {
+				log.Printf("lifecycle: delete licenses for instance %s: %v", inst.InstanceID, err)
+			}
+		}
+
 		due := dueNotice(now, lic.ExpiresAt, inst.NoticesSent)
 		if due == "" {
 			continue

agent/internal/grpc/client.go

@@ -151,3 +151,7 @@ func (c *Client) ReportChecks(serverID, agentToken string, results []pb.CheckRes
 func (c *Client) CommandStream(ctx context.Context) (pb.Vantage_CommandStreamClient, error) {
 	return c.client.CommandStream(ctx)
 }
+
+func (c *Client) ProxyStream(ctx context.Context) (pb.Vantage_ProxyStreamClient, error) {
+	return c.client.ProxyStream(ctx)
+}

agent/internal/grpc/pb/vantage.pb.go

@@ -131,6 +131,32 @@ type ReportChecksResponse struct{}
 
 type ApplyUpdatesCmd struct{}
 
+type OpenProxyCmd struct {
+	ProxyId string `json:"proxy_id"`
+	Port    uint32 `json:"port"`
+}
+
+type ProxyOpen struct {
+	ServerId   string `json:"server_id"`
+	AgentToken string `json:"agent_token"`
+	ProxyId    string `json:"proxy_id"`
+}
+
+type ProxyClose struct {
+	Reason string `json:"reason,omitempty"`
+}
+
+type ProxyClientMsg struct {
+	Open  *ProxyOpen  `json:"open,omitempty"`
+	Data  []byte      `json:"data,omitempty"`
+	Close *ProxyClose `json:"close,omitempty"`
+}
+
+type ProxyServerMsg struct {
+	Data  []byte      `json:"data,omitempty"`
+	Close *ProxyClose `json:"close,omitempty"`
+}
+
 type ServerCommand struct {
 	CommandId        string               `json:"command_id"`
 	GenerateKey      *GenerateKeyCmd      `json:"generate_key,omitempty"`
@@ -139,6 +165,7 @@ type ServerCommand struct {
 	ApplyUpdates     *ApplyUpdatesCmd     `json:"apply_updates,omitempty"`
 	RunStep          *RunStepCmd          `json:"run_step,omitempty"`
 	CleanupWorkspace *CleanupWorkspaceCmd `json:"cleanup_workspace,omitempty"`
+	OpenProxy        *OpenProxyCmd        `json:"open_proxy,omitempty"`
 }
 
 
@@ -254,6 +281,51 @@ func (s *keyManagerCommandStreamServer) Recv() (*AgentMessage, error) {
 	return m, nil
 }
 
+type Vantage_ProxyStreamServer interface {
+	Send(*ProxyServerMsg) error
+	Recv() (*ProxyClientMsg, error)
+	grpc.ServerStream
+}
+
+type vantageProxyStreamServer struct {
+	grpc.ServerStream
+}
+
+func (s *vantageProxyStreamServer) Send(m *ProxyServerMsg) error {
+	return s.ServerStream.SendMsg(m)
+}
+
+func (s *vantageProxyStreamServer) Recv() (*ProxyClientMsg, error) {
+	m := new(ProxyClientMsg)
+	if err := s.ServerStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+type Vantage_ProxyStreamClient interface {
+	Send(*ProxyClientMsg) error
+	Recv() (*ProxyServerMsg, error)
+	CloseSend() error
+	grpc.ClientStream
+}
+
+type vantageProxyStreamClient struct {
+	grpc.ClientStream
+}
+
+func (c *vantageProxyStreamClient) Send(m *ProxyClientMsg) error {
+	return c.ClientStream.SendMsg(m)
+}
+
+func (c *vantageProxyStreamClient) Recv() (*ProxyServerMsg, error) {
+	m := new(ProxyServerMsg)
+	if err := c.ClientStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
 type VantageClient interface {
 	Register(ctx context.Context, in *RegisterRequest, opts ...grpc.CallOption) (*RegisterResponse, error)
 	SyncKeys(ctx context.Context, in *SyncRequest, opts ...grpc.CallOption) (*SyncResponse, error)
@@ -263,6 +335,7 @@ type VantageClient interface {
 	SyncMonitors(ctx context.Context, in *SyncMonitorsRequest, opts ...grpc.CallOption) (*SyncMonitorsResponse, error)
 	ReportChecks(ctx context.Context, in *ReportChecksRequest, opts ...grpc.CallOption) (*ReportChecksResponse, error)
 	CommandStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_CommandStreamClient, error)
+	ProxyStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_ProxyStreamClient, error)
 }
 
 type UnimplementedVantageServer struct{}
@@ -349,3 +422,12 @@ func (c *keyManagerClient) CommandStream(ctx context.Context, opts ...grpc.CallO
 	}
 	return &vantageCommandStreamClient{stream}, nil
 }
+
+func (c *keyManagerClient) ProxyStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_ProxyStreamClient, error) {
+	desc := &grpc.StreamDesc{StreamName: "ProxyStream", ServerStreams: true, ClientStreams: true}
+	stream, err := c.cc.NewStream(ctx, desc, "/vantage.v1.Vantage/ProxyStream", opts...)
+	if err != nil {
+		return nil, err
+	}
+	return &vantageProxyStreamClient{stream}, nil
+}

agent/internal/proxy/proxy.go

@@ -0,0 +1,114 @@
+// Package agentproxy relays a single TCP connection between a local service and
+// the control plane, so a control plane that cannot route to this host's network
+// can still open a console session.
+//
+// The dial host is hardcoded to loopback. The control plane supplies only a
+// port, and nothing in this package can be made to dial anywhere else.
+package agentproxy
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"strconv"
+	"time"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/agent/internal/grpc/pb"
+)
+
+const (
+	loopbackHost = "127.0.0.1"
+	chunkSize    = 32 * 1024
+	dialTimeout  = 10 * time.Second
+)
+
+// Stream is the agent's half of a ProxyStream.
+type Stream interface {
+	Send(*pb.ProxyClientMsg) error
+	Recv() (*pb.ProxyServerMsg, error)
+	CloseSend() error
+}
+
+// Open dials the local port, announces itself on the stream, and relays until
+// either side ends. A refused dial is reported as an explicit close so the
+// operator sees a reason rather than a hang.
+func Open(stream Stream, serverID, agentToken, proxyID string, port uint32) error {
+	conn, dialErr := net.DialTimeout("tcp",
+		net.JoinHostPort(loopbackHost, strconv.Itoa(int(port))), dialTimeout)
+
+	if err := stream.Send(&pb.ProxyClientMsg{Open: &pb.ProxyOpen{
+		ServerId:   serverID,
+		AgentToken: agentToken,
+		ProxyId:    proxyID,
+	}}); err != nil {
+		if conn != nil {
+			_ = conn.Close()
+		}
+		return fmt.Errorf("send open: %w", err)
+	}
+
+	if dialErr != nil {
+		_ = stream.Send(&pb.ProxyClientMsg{Close: &pb.ProxyClose{
+			Reason: "dial_refused: " + dialErr.Error(),
+		}})
+		_ = stream.CloseSend()
+		return fmt.Errorf("dial 127.0.0.1:%d: %w", port, dialErr)
+	}
+	defer conn.Close()
+
+	return relay(conn, stream)
+}
+
+func relay(conn net.Conn, stream Stream) error {
+	errCh := make(chan error, 2)
+
+	// local service -> control plane
+	go func() {
+		buf := make([]byte, chunkSize)
+		for {
+			n, err := conn.Read(buf)
+			if n > 0 {
+				chunk := make([]byte, n)
+				copy(chunk, buf[:n])
+				if sendErr := stream.Send(&pb.ProxyClientMsg{Data: chunk}); sendErr != nil {
+					errCh <- sendErr
+					return
+				}
+			}
+			if err != nil {
+				errCh <- err
+				return
+			}
+		}
+	}()
+
+	// control plane -> local service
+	go func() {
+		for {
+			msg, err := stream.Recv()
+			if err != nil {
+				errCh <- err
+				return
+			}
+			if msg.Close != nil {
+				errCh <- fmt.Errorf("server closed relay: %s", msg.Close.Reason)
+				return
+			}
+			if len(msg.Data) > 0 {
+				if _, err := conn.Write(msg.Data); err != nil {
+					errCh <- err
+					return
+				}
+			}
+		}
+	}()
+
+	err := <-errCh
+	_ = conn.Close()
+	_ = stream.CloseSend()
+	if errors.Is(err, io.EOF) {
+		return nil
+	}
+	return err
+}

agent/internal/sync/sync.go

@@ -24,6 +24,7 @@ import (
 	"gitea.hostxtra.co.uk/mrhid6/vantage/agent/internal/inventory"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/agent/internal/keys"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/agent/internal/monitors"
+	agentproxy "gitea.hostxtra.co.uk/mrhid6/vantage/agent/internal/proxy"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/agent/internal/updates"
 )
 
@@ -197,6 +198,9 @@ func connectAndHandleStream(ctx context.Context, cfg *config.Config) error {
 		if cmd.CleanupWorkspace != nil {
 			go handleCleanupWorkspace(cmd)
 		}
+		if cmd.OpenProxy != nil {
+			go handleOpenProxy(ctx, cfg, cmd.OpenProxy)
+		}
 		if cmd.RunStep != nil {
 			go func(rc *pb.RunStepCmd, cid string) {
 				emit := func(seq uint64, data []byte) {
@@ -326,6 +330,29 @@ func handleCleanupWorkspace(cmd *pb.ServerCommand) {
 	log.Printf("removed run workspace %s (cmd=%s)", dir, cmd.CommandId)
 }
 
+// handleOpenProxy relays one console connection. It uses its own gRPC
+// connection so console traffic never shares a stream with commands, key sync
+// or workflow output.
+func handleOpenProxy(ctx context.Context, cfg *config.Config, cmd *pb.OpenProxyCmd) {
+	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
+	if err != nil {
+		log.Printf("proxy %s: dial control plane: %v", cmd.ProxyId, err)
+		return
+	}
+	defer client.Close()
+
+	stream, err := client.ProxyStream(ctx)
+	if err != nil {
+		log.Printf("proxy %s: open stream: %v", cmd.ProxyId, err)
+		return
+	}
+
+	log.Printf("proxy %s: relaying 127.0.0.1:%d", cmd.ProxyId, cmd.Port)
+	if err := agentproxy.Open(stream, cfg.ServerID, cfg.AgentToken, cmd.ProxyId, cmd.Port); err != nil {
+		log.Printf("proxy %s: %v", cmd.ProxyId, err)
+	}
+}
+
 func handleDeleteKey(cmd *pb.ServerCommand) {
 	label := cmd.DeleteKey.Label
 	keyPath := fmt.Sprintf("/root/.ssh/vantage_%s", strings.ReplaceAll(label, " ", "_"))

claude.md

@@ -138,7 +138,22 @@ Key/value pairs grouped by name, encrypted at rest with AES-256-GCM. Consumed tw
 
 ### Browser console
 
-`POST /api/console/connect` mints a one-time session token; `GET /api/console/tunnel` upgrades to a WebSocket and proxies to **guacd** (Apache Guacamole daemon) using `github.com/wwt/guac`. SSH connections authenticate with a stored private key; RDP/VNC credentials are encrypted, single-use, and consumed when the tunnel opens.
+`POST /api/console/connect` mints a one-time session token; `GET /api/console/tunnel`
+upgrades to a WebSocket and proxies to **guacd** using `github.com/wwt/guac`.
+
+guacd never dials the managed server. The server binds a single-use ephemeral
+listener, pushes `OpenProxyCmd` down the agent's command stream, and the agent
+opens a `ProxyStream` and relays the connection from its own **`127.0.0.1`** —
+the host is hardcoded agent-side, so the control plane can name only a port.
+This is what makes the console work on Vantage Cloud, where the customer's
+server is behind NAT on a private address. It also means the console now
+**requires a live agent** on every deployment: `consoleConnect` answers 409
+`agent_offline` rather than hanging.
+
+SSH connections authenticate with a stored private key; RDP/VNC credentials are
+encrypted, single-use, and consumed when the tunnel opens. None of them reach
+the agent — the session is negotiated end-to-end between guacd and the target
+daemon, so the agent relays bytes it cannot read.
 
 ### Inventory and OS updates
 
@@ -517,6 +532,8 @@ Windows: MSI built by CI (WiX), or `installer/setup.ps1` registering the agent a
 | `REDIS_ADDR`               | no              | default `localhost:6379`                                                                                                                                                                                                                                                                                           |
 | `KEY_ENCRYPTION_KEY`       | yes in practice | 64-char hex (32 bytes) for AES-256-GCM. Required for private keys, secrets, OIDC secrets, RDP credentials.                                                                                                                                                                                                         |
 | `GUACD_ADDR`               | no              | default `guacd:4822`                                                                                                                                                                                                                                                                                               |
+| `PROXY_ADVERTISE_HOST`     | no              | default `server`; the hostname guacd resolves the control plane by, handed to guacd as the relay's address. Wrong here and every console session fails at connect                                                                                                                                                |
+| `PROXY_LISTEN_HOST`        | no              | default `0.0.0.0`; the interface the ephemeral relay listener binds                                                                                                                                                                                                                                                |
 | `APP_ROOT_LABEL`           | no              | default `vantage`; wrong value disables the host/session org guard                                                                                                                                                                                                                                                 |
 | `VANTAGE_WORKFLOW_LOG_DIR` | no              | where run logs are written                                                                                                                                                                                                                                                                                         |
 | `FREE_INSTANCE_REAP_AFTER` | no              | duration past a Free licence's expiry before the instance and all its data are deleted. **Empty disables the reaper, and empty is the default.** Set to `336h` in `docker-compose.site.yml` only — a self-hosted deployment must never reap. Must match admin's value, which only names the date in warning emails |

deploy/agent.service

@@ -1,23 +0,0 @@
-[Unit]
-Description=Vantage Agent
-Documentation=https://github.com/your-org/vantage
-After=network.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-ExecStart=/usr/local/bin/vantage-agent
-Restart=always
-RestartSec=10
-User=root
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=vantage-agent
-
-# Security hardening
-NoNewPrivileges=true
-ProtectSystem=false
-ProtectHome=false
-
-[Install]
-WantedBy=multi-user.target

deploy/chart/vantage/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: vantage
+description: Helm chart for the Vantage stack (Redis, MongoDB, guacd, server, web)
+type: application
+version: 0.1.0
+appVersion: "1.0.0"

deploy/chart/vantage/templates/NOTES.txt

@@ -0,0 +1,17 @@
+Vantage has been deployed as release "{{ .Release.Name }}" in namespace "{{ .Release.Namespace }}".
+
+Services created:
+  - {{ .Release.Name }}-redis   (ClusterIP {{ .Values.redis.port }})
+  - {{ .Release.Name }}-mongo   (ClusterIP {{ .Values.mongo.port }})
+  - {{ .Release.Name }}-guacd   ({{ .Values.guacd.service.type }} {{ .Values.guacd.service.port }})
+  - {{ .Release.Name }}-server  ({{ .Values.server.service.type }} http:{{ .Values.server.service.httpPort }} grpc:{{ .Values.server.service.grpcPort }})
+  - {{ .Release.Name }}-web     ({{ .Values.web.service.type }} {{ .Values.web.service.port }})
+
+By default the server/web/guacd services are ClusterIP only (no host port publishing,
+unlike the original docker-compose file). To expose them externally, set
+server.service.type / web.service.type / guacd.service.type to NodePort or LoadBalancer,
+or add an Ingress on top of the -web and -server services.
+
+Quick access via port-forward, e.g.:
+  kubectl port-forward svc/{{ .Release.Name }}-web {{ .Values.web.service.port }}:{{ .Values.web.service.port }}
+  kubectl port-forward svc/{{ .Release.Name }}-server {{ .Values.server.service.httpPort }}:{{ .Values.server.service.httpPort }}

deploy/chart/vantage/templates/_helpers.tpl

@@ -0,0 +1,11 @@
+{{/*
+Common name helpers
+*/}}
+{{- define "vantage.fullname" -}}
+{{ .Release.Name }}
+{{- end -}}
+
+{{- define "vantage.labels" -}}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}

deploy/chart/vantage/templates/guacd.yaml

@@ -0,0 +1,44 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-guacd
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: guacd
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: guacd
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: guacd
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: guacd
+          image: "{{ .Values.guacd.image.repository }}:{{ .Values.guacd.image.tag }}"
+          ports:
+            - containerPort: 4822
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-guacd
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: guacd
+spec:
+  type: {{ .Values.guacd.service.type }}
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: guacd
+  ports:
+    - port: {{ .Values.guacd.service.port }}
+      targetPort: 4822

deploy/chart/vantage/templates/mongo.yaml

@@ -0,0 +1,90 @@
+{{- if .Values.mongo.persistence.enabled }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Release.Name }}-mongo-data
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: mongo
+spec:
+  accessModes:
+    - {{ .Values.mongo.persistence.accessMode }}
+  {{- if .Values.mongo.persistence.storageClass }}
+  storageClassName: {{ .Values.mongo.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.mongo.persistence.size }}
+---
+{{- end }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-mongo
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: mongo
+spec:
+  replicas: 1
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: mongo
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: mongo
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: mongo
+          image: "{{ .Values.mongo.image.repository }}:{{ .Values.mongo.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.mongo.port }}
+          volumeMounts:
+            - name: mongo-data
+              mountPath: /data/db
+          livenessProbe:
+            exec:
+              command: ["mongosh", "--quiet", "--eval", "db.adminCommand('ping')"]
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+          readinessProbe:
+            exec:
+              command: ["mongosh", "--quiet", "--eval", "db.adminCommand('ping')"]
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+      volumes:
+        - name: mongo-data
+          {{- if .Values.mongo.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Release.Name }}-mongo-data
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-mongo
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: mongo
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: mongo
+  ports:
+    - port: {{ .Values.mongo.port }}
+      targetPort: {{ .Values.mongo.port }}

deploy/chart/vantage/templates/redis.yaml

@@ -0,0 +1,90 @@
+{{- if .Values.redis.persistence.enabled }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Release.Name }}-redis-data
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: redis
+spec:
+  accessModes:
+    - {{ .Values.redis.persistence.accessMode }}
+  {{- if .Values.redis.persistence.storageClass }}
+  storageClassName: {{ .Values.redis.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.redis.persistence.size }}
+---
+{{- end }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-redis
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: redis
+spec:
+  replicas: 1
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: redis
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: redis
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: redis
+          image: "{{ .Values.redis.image.repository }}:{{ .Values.redis.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.redis.port }}
+          volumeMounts:
+            - name: redis-data
+              mountPath: /data
+          livenessProbe:
+            exec:
+              command: ["redis-cli", "ping"]
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+          readinessProbe:
+            exec:
+              command: ["redis-cli", "ping"]
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+      volumes:
+        - name: redis-data
+          {{- if .Values.redis.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Release.Name }}-redis-data
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-redis
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: redis
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: redis
+  ports:
+    - port: {{ .Values.redis.port }}
+      targetPort: {{ .Values.redis.port }}

deploy/chart/vantage/templates/server.yaml

@@ -0,0 +1,123 @@
+{{- if and .Values.server.persistence.enabled (not .Values.server.persistence.useHostPath) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Release.Name }}-server-data
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  accessModes:
+    - {{ .Values.server.persistence.accessMode }}
+  {{- if .Values.server.persistence.storageClass }}
+  storageClassName: {{ .Values.server.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.server.persistence.size }}
+---
+{{- end }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-server
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: server
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: server
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      # Wait for redis & mongo to be reachable, approximating compose's
+      # `depends_on: condition: service_healthy`
+      initContainers:
+        - name: wait-for-redis
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z {{ .Release.Name }}-redis {{ .Values.redis.port }}; do
+                echo "waiting for redis..."; sleep 2;
+              done
+        - name: wait-for-mongo
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z {{ .Release.Name }}-mongo {{ .Values.mongo.port }}; do
+                echo "waiting for mongo..."; sleep 2;
+              done
+      containers:
+        - name: server
+          image: "{{ .Values.server.image.repository }}:{{ .Values.server.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.server.service.httpPort }}
+            - containerPort: {{ .Values.server.service.grpcPort }}
+          env:
+            - name: MONGO_URI
+              value: {{ tpl .Values.server.env.mongoUri . | quote }}
+            - name: REDIS_ADDR
+              value: "{{ .Release.Name }}-redis:{{ .Values.redis.port }}"
+            - name: GRPC_HOST
+              value: {{ .Values.server.env.grpcHost | quote }}
+            - name: GRPC_PORT
+              value: {{ .Values.server.service.grpcPort | quote }}
+            - name: HTTP_PORT
+              value: {{ .Values.server.service.httpPort | quote }}
+            - name: KEY_ENCRYPTION_KEY
+              value: {{ .Values.server.env.keyEncryptionKey | quote }}
+            - name: VANTAGE_WORKFLOW_LOG_DIR
+              value: {{ .Values.server.env.vantageWorkflowLogDir | quote }}
+            - name: GUACD_ADDR
+              value: "{{ .Release.Name }}-guacd:{{ .Values.guacd.service.port }}"
+            - name: APP_ROOT_LABEL
+              value: {{ .Values.server.env.appRootLabel | quote }}
+            - name: PROXY_ADVERTISE_HOST
+              value: {{ .Values.server.env.proxyAdvertiseHost | quote }}
+            - name: PROXY_LISTEN_HOST
+              value: {{ .Values.server.env.proxyListenHost | quote }}
+          volumeMounts:
+            - name: server-data
+              mountPath: /data
+      volumes:
+        - name: server-data
+          {{- if .Values.server.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Release.Name }}-server-data
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-server
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  type: {{ .Values.server.service.type }}
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: server
+  ports:
+    - name: http
+      port: {{ .Values.server.service.httpPort }}
+      targetPort: {{ .Values.server.service.httpPort }}
+    - name: grpc
+      port: {{ .Values.server.service.grpcPort }}
+      targetPort: {{ .Values.server.service.grpcPort }}

deploy/chart/vantage/templates/web.yaml

@@ -0,0 +1,57 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-web
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: web
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: web
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: web
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      initContainers:
+        - name: wait-for-server
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z {{ .Release.Name }}-server {{ .Values.server.service.httpPort }}; do
+                echo "waiting for server..."; sleep 2;
+              done
+      containers:
+        - name: web
+          image: "{{ .Values.web.image.repository }}:{{ .Values.web.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.web.service.port }}
+          env:
+            - name: API_URL
+              value: {{ tpl .Values.web.env.apiUrl . | quote }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-web
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: web
+spec:
+  type: {{ .Values.web.service.type }}
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: web
+  ports:
+    - port: {{ .Values.web.service.port }}
+      targetPort: {{ .Values.web.service.port }}

deploy/chart/vantage/values.yaml

@@ -0,0 +1,66 @@
+# Default values for the vantage chart.
+
+redis:
+    image:
+        repository: redis
+        tag: "8"
+    persistence:
+        enabled: true
+        size: 1Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+    port: 6379
+
+mongo:
+    image:
+        repository: mongo
+        tag: "7"
+    persistence:
+        enabled: true
+        size: 5Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+    port: 27017
+
+guacd:
+    image:
+        repository: docker.io/guacamole/guacd
+        tag: "1.6.0"
+    service:
+        type: ClusterIP
+        port: 4822
+
+server:
+    image:
+        repository: gitea.hostxtra.co.uk/mrhid6/vantage/server
+        tag: latest
+    service:
+        type: ClusterIP
+        httpPort: 8080
+        grpcPort: 9090
+    env:
+        mongoUri: "mongodb://{{ .Release.Name }}-mongo:27017/vantage"
+        grpcHost: "{{ .Release.Name }}-server:9090"
+        keyEncryptionKey: ""
+        vantageWorkflowLogDir: ""
+        appRootLabel: vantage
+        proxyAdvertiseHost: "{{ .Release.Name }}-server"
+        proxyListenHost: "0.0.0.0"
+    persistence:
+        enabled: true
+        size: 1Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+        hostPath: /data
+
+web:
+    image:
+        repository: gitea.hostxtra.co.uk/mrhid6/vantage/web
+        tag: latest
+    service:
+        type: ClusterIP
+        port: 3000
+    env:
+        apiUrl: "http://{{ .Release.Name }}-server:8080"
+
+imagePullSecrets: []

deploy/docker/.env.example

@@ -5,7 +5,7 @@
 
 # host:port agents dial for gRPC. No default; boot fails without it.
 # Must be reachable from managed servers. Use the public host, port 9090.
-GRPC_HOST=192.168.1.250:9090
+GRPC_HOST=vantage.yourdomain.com:9090
 
 # 64-char hex (32 bytes) for AES-256-GCM. Required for private keys,
 # secrets, OIDC secrets, RDP/VNC credentials.

deploy/docker/docker-compose.yml

@@ -47,7 +47,7 @@ services:
             KEY_ENCRYPTION_KEY: ${KEY_ENCRYPTION_KEY:-}
             VANTAGE_WORKFLOW_LOG_DIR: ${VANTAGE_WORKFLOW_LOG_DIR:-}
             GUACD_ADDR: guacd:4822
-            APP_ROOT_LABEL: vantage
+            PROXY_ADVERTISE_HOST: server
         depends_on:
             redis:
                 condition: service_healthy

docs/superpowers/specs/2026-07-29-agent-console-proxy-design.md

@@ -0,0 +1,209 @@
+# Agent-relayed console proxy
+
+Date: 2026-07-29
+Status: approved, not yet implemented
+
+## Problem
+
+`consoleTunnel` builds guacamole parameters from `srv.IPAddress` and hands them
+to guacd, which then dials the target itself. On a self-hosted deployment the
+control plane and the managed servers share a network, so that works. On Vantage
+Cloud they do not: guacd runs on the cloud host and the customer's server is on
+an RFC1918 address behind their NAT. Every cloud console session to a private
+address fails, for SSH, RDP and VNC alike.
+
+Agents already hold an outbound gRPC connection to the control plane. The fix is
+to carry the console's TCP bytes over that existing path rather than asking guacd
+to route somewhere it cannot reach.
+
+## Decisions
+
+**Self-relay only.** The agent relays to its own host and nowhere else. It is
+never told a hostname; the host is hardcoded to `127.0.0.1` on the agent side and
+only the port comes from the server. A jump-host mode (reaching agentless devices
+through a neighbouring agent) was rejected: it would give an agent the power to
+dial arbitrary addresses on the customer's LAN, and the console today can only
+target servers that run an agent anyway.
+
+**A dedicated bidirectional RPC, one stream per TCP connection.** Multiplexing
+console bytes onto the existing `CommandStream` was rejected — that stream
+already carries control commands and workflow stdout, and an RDP framebuffer
+would introduce head-of-line blocking against key sync and step output. A
+separate stream also gets connection lifetime, flow control and close semantics
+for free instead of needing a hand-rolled connection-ID demux.
+
+**Always proxy, both deployments.** Direct dial is deleted rather than kept as a
+self-hosted fast path or a fallback. One code path means one tested code path,
+and the cloud path is the one no developer can reproduce locally. A
+try-direct-then-fall-back design was rejected outright: it puts a timeout in
+front of every private-network session and makes "which path did this session
+use" unanswerable from the audit log.
+
+The cost is that the console now requires a live agent, where a self-hosted
+deployment could previously reach a server whose agent was down. In practice an
+offline agent almost always means an offline host, and the failure is now an
+immediate, explicit refusal instead of a hang.
+
+## Architecture
+
+Three parties rendezvous on a single `proxy_id`. Neither guacd nor the agent
+changes which direction it dials: guacd still makes an outbound TCP connection,
+the agent still only connects outbound to the control plane.
+
+```
+consoleTunnel (server)
+  1. proxy.Open(instance, server_id, port) -> proxy_id + ephemeral listener :N
+  2. push OpenProxyCmd{proxy_id, port} down the existing CommandStream
+  3. agent dials 127.0.0.1:port locally, then opens ProxyStream and sends
+     ProxyOpen{server_id, agent_token, proxy_id}
+  4. guacd dials PROXY_ADVERTISE_HOST:N  (the params it was handed in step 1)
+  5. registry holds both halves -> io.Copy in both directions
+  6. either side EOFs -> close listener, close stream, drop the registry entry
+```
+
+Steps 3 and 4 race, so a registry entry has two slots and starts piping when the
+second one arrives. Both waits share a single 10 second deadline; expiry closes
+everything and frees the entry.
+
+The agent dials locally *before* opening the stream, so a refused connection
+arrives as an explicit `ProxyClose{reason}` rather than as a hang.
+
+`BuildGuacParams` stops reading `srv.IPAddress` and takes the relay host and port
+instead. `IPAddress` remains in use for display and for monitors.
+
+## Wire protocol
+
+Additive only; no existing message changes shape.
+
+```protobuf
+rpc ProxyStream(stream ProxyClientMsg) returns (stream ProxyServerMsg);
+
+message OpenProxyCmd {            // ServerCommand oneof field 8
+  string proxy_id = 1;
+  uint32 port     = 2;
+}
+
+message ProxyClientMsg {
+  oneof payload {
+    ProxyOpen  open  = 1;         // first message only
+    bytes      data  = 2;
+    ProxyClose close = 3;
+  }
+}
+message ProxyOpen  { string server_id = 1; string agent_token = 2; string proxy_id = 3; }
+message ProxyServerMsg { oneof payload { bytes data = 1; ProxyClose close = 2; } }
+message ProxyClose { string reason = 1; }
+```
+
+Two implementation facts about this repo shape the above. The `pb` packages are
+**hand-written Go, not protoc output** — `vantage.proto` is documentation, and
+both `server/internal/grpc/pb` and `agent/internal/grpc/pb` are edited by hand
+and kept in sync manually. And the registered codec is JSON, so a `bytes` field
+travels as a base64 string: roughly 33% overhead on relayed traffic. That is
+accepted rather than fixed here, because introducing a second codec for one RPC
+is a larger change than this feature warrants. Relay chunks are 32 KiB.
+
+## Security
+
+**The agent only ever dials `127.0.0.1`.** The port is the only field it takes
+from the server; the host is hardcoded agent-side. A compromised control plane
+cannot use an agent to reach anything else on the customer's network. This is the
+strongest property in the design and the reason self-relay was chosen.
+
+**`proxy_id` is 32 random bytes, single-use and scoped.** On `ProxyOpen` the
+server checks three things together: the agent token hash matches that
+`server_id`, the `proxy_id` exists in the registry, and the entry's `server_id`
+and `instance_id` match the authenticated agent. Any mismatch closes the stream
+without revealing which check failed.
+
+**The listener is the exposed surface and is narrowed four ways.** It binds an
+ephemeral port; it lives at most 10 seconds unclaimed; it accepts exactly one
+connection and closes immediately afterwards; and the accepted connection's
+remote address must resolve to a host named in `GUACD_ADDR`. Without that last
+check, any other container on the Docker network could claim the session during
+the window.
+
+**Agent-offline is refused early.** `consoleConnect` checks
+`srv.Status == "active"` and returns 409 `agent_offline`, rather than letting the
+browser open a WebSocket that dies on a deadline.
+
+**Audit.** `console.opened` gains the relay port and `proxy_id`. A relay that
+expires or is refused writes `console.proxy_failed` with a reason, so a failed
+console session stops being invisible.
+
+Credentials are unchanged. Private keys and RDP passwords travel from the server
+to guacd inside the guacamole handshake and never reach the agent. The SSH and
+RDP sessions are negotiated end-to-end between guacd and the target daemon, so
+the agent relays bytes it cannot read.
+
+## Components
+
+New, server:
+
+| Unit | Responsibility |
+| --- | --- |
+| `server/internal/proxy/registry.go` | `Open`, `AttachAgent`, `AttachTCP`, expiry sweep. Pure state — no net, no gRPC, testable alone |
+| `server/internal/proxy/session.go` | One relay: listener, deadline, the `io.Copy` pair, teardown-once |
+| `server/internal/grpc/proxystream.go` | The `ProxyStream` handler: authenticate, then hand the stream to the registry. No relay logic of its own |
+
+New, agent:
+
+| Unit | Responsibility |
+| --- | --- |
+| `agent/internal/proxy/proxy.go` | `Open(ctx, client, proxyID, port)` — dial loopback, open the stream, pump bytes. No build tags; Linux and Windows share it |
+
+Changed:
+
+- `proto/vantage/v1/vantage.proto`, and both generated pb trees
+- `server/internal/services/console.go` — `BuildGuacParams(srv, relayHost, relayPort, …)`
+- `server/internal/api/console.go` — offline pre-check in `consoleConnect`; open the relay before the guacd handshake in `consoleTunnel` and close it in `OnDisconnect`
+- `agent/internal/sync/sync.go` — handle `OpenProxyCmd`, one goroutine per proxy
+- `deploy/docker-compose.yml`, `deploy/docker-compose.site.yml` — `PROXY_ADVERTISE_HOST=server`
+
+Two new optional environment variables on the server: `PROXY_ADVERTISE_HOST`
+(default `server`, the name guacd resolves the control plane by) and
+`PROXY_LISTEN_HOST` (default `0.0.0.0`).
+
+Nothing new is opened on the customer's firewall — the relay rides the agent's
+existing outbound gRPC connection.
+`docsite/docs/reference/ports-and-networking.md` and
+`docsite/docs/vantage/browser-console.md` must say so, and must state the new
+requirement that the agent be online.
+
+A secondary benefit beyond cloud: a VNC or RDP service bound only to `127.0.0.1`
+is now reachable, where a direct dial from guacd never could be.
+
+## Failure modes
+
+| Failure | Behaviour |
+| --- | --- |
+| Agent offline at connect | 409 `agent_offline` from `consoleConnect`, before any WebSocket is opened |
+| Agent never opens the stream | 10s deadline; listener closed; `console.proxy_failed{reason:"agent_timeout"}`; WebSocket closed with a message the UI surfaces |
+| Local dial refused (daemon down, wrong port) | `ProxyClose{reason}` relayed up as the same audit event, reason `dial_refused` |
+| guacd never dials | Same deadline path, reason `guacd_timeout` |
+| Bad token, unknown or foreign `proxy_id` | Stream closed with no detail leaked; `console.proxy_failed{reason:"rejected"}` |
+| Agent process dies mid-session | Stream EOF, relay torn down, console shows a disconnect |
+| CommandStream reconnects mid-session | No effect on live sessions — the relay is on its own stream. Only a new `OpenProxyCmd` needs the control stream |
+
+Teardown is guarded by `sync.Once` on both sides: both `io.Copy` goroutines
+finish, and whichever finishes second must not double-close.
+
+## Testing
+
+Written test-first.
+
+- `server/internal/proxy/registry_test.go` — the two halves pair in either
+  order; expiry frees the entry; a second claim on a used `proxy_id` is
+  rejected; a mismatched `instance_id` is rejected. No network.
+- `server/internal/proxy/session_test.go` — two `net.Pipe` halves; bytes flow
+  both ways; EOF in each direction tears down; double-close is safe.
+- `server/internal/grpc/proxystream_test.go` — the authentication matrix: valid,
+  wrong token, unknown `proxy_id`, `proxy_id` belonging to another instance.
+- `agent/internal/proxy` — a refused dial emits `ProxyClose`; the happy path
+  echoes bytes.
+- End-to-end in `server`: a fake agent plus a `net.Listen` echo server, asserting
+  bytes traverse listener → registry → stream → echo and back. This is the test
+  that would have caught the original bug.
+
+Manual verification, in this order: self-hosted SSH (proves no regression),
+cloud SSH to a private-network host, cloud RDP to a Windows agent.

docsite/docs/reference/environment-variables.md

@@ -17,6 +17,8 @@ it is absent.
 | `KEY_ENCRYPTION_KEY`       | yes in practice |                             | 64 hex characters (32 bytes) for AES-256-GCM. Required for private keys, vault secrets, OIDC client secrets and console credentials                                |
 | `GITEA_HOST`               | yes             | `gitea.example.com`         | Used to build the install scripts and agent download URLs. The default is a placeholder that will not resolve                                                      |
 | `GUACD_ADDR`               | no              | `guacd:4822`                | The [browser console](../vantage/browser-console.md) daemon                                                                                                        |
+| `PROXY_ADVERTISE_HOST`     | no              | `server`                    | The hostname **guacd** uses to reach the control plane's console relay. Wrong here and every console session fails at connect with guacd unable to resolve the relay |
+| `PROXY_LISTEN_HOST`        | no              | `0.0.0.0`                   | Interface the ephemeral relay listeners bind. Narrow it only if guacd shares a known interface                                                                     |
 | `APP_ROOT_LABEL`           | no              | `vantage`                   | The app root label for the host and session organisation guard                                                                                                     |
 | `VANTAGE_WORKFLOW_LOG_DIR` | no              |                             | Where workflow run logs are written                                                                                                                                |
 

docsite/docs/reference/ports-and-networking.md

@@ -24,7 +24,8 @@ flowchart LR
     W --> S["server :8080"]
     A["Agent on a managed server"] -->|"gRPC/TLS :9090, outbound"| S
     S --> G["guacd :4822"]
-    G -->|"SSH / RDP / VNC"| T["Target machine"]
+    G -->|"relayed over the :9090 stream"| A
+    A -->|"SSH / RDP / VNC, loopback"| T["Target machine (same host as agent)"]
 ```
 
 Two things are worth reading off that diagram.
@@ -33,9 +34,13 @@ Two things are worth reading off that diagram.
 NAT is not an obstacle. The only requirement is that the machine can reach
 `GRPC_HOST`.
 
-**The console does not use the agent.** guacd connects directly to the target on
-the protocol port. A machine reachable only by its agent behind NAT, on a
-private subnet cannot be consoled, even though every other feature works.
+**The console rides the agent's connection too.** guacd never dials the target
+directly; the server pushes a command down the agent's existing outbound gRPC
+stream on `9090`, and the agent relays the protocol traffic from its own
+loopback. No route from the control plane to the target's address is needed,
+and no new inbound port opens on the target — the same connection that carries
+key sync carries console traffic. This is what makes the console work for a
+machine behind NAT on a private subnet, as long as its agent is online.
 
 ## What to open
 
@@ -49,7 +54,9 @@ private subnet cannot be consoled, even though every other feature works.
 - `gitea.hostxtra.co.uk`, for agent releases and version checks.
 - Anything a server-run [monitor](../vantage/monitors.md) checks.
 - SMTP, if you use an SMTP notification channel.
-- Protocol ports on machines you intend to console.
+
+No route to the machines you intend to console is needed — that traffic rides
+the agent's existing outbound `9090` connection instead.
 
 ### Outbound from a managed machine
 

docsite/docs/reference/troubleshooting.md

@@ -86,7 +86,7 @@ instantaneous.
 | Connects, then closes at once | guacd unreachable. Check `GUACD_ADDR` and that the container is running                                         |
 | SSH rejects the key           | The stored key has no private half, or is not on the target                                                     |
 | RDP fails on retry            | Credentials are single-use and consumed at tunnel open enter them again                                         |
-| Hangs at "connecting"         | The **control plane** cannot reach the target on the protocol port. The agent's reachability is irrelevant here |
+| Hangs, then disconnects        | The agent never claimed the relay, nothing is listening on the protocol port on the target's own loopback address, or guacd never dialled in time. Check the audit log for `console.proxy_failed` — its reason (`agent_timeout`, `dial_refused`, `guacd_timeout`, `rejected`) names which |
 | Fails only in production      | The reverse proxy is not forwarding WebSocket upgrade headers                                                   |
 
 ## Monitors report down when the service is up

docsite/docs/vantage/browser-console.md

@@ -15,17 +15,20 @@ to a **guacd** daemon and manages credentials around it.
 - `guacd` running and reachable from the server. The bundled Compose stack
   includes it; `GUACD_ADDR` defaults to `guacd:4822`.
 - `KEY_ENCRYPTION_KEY` set, since every credential involved is stored encrypted.
-- Network reachability **from the control plane to the target** on the protocol
-  port. This is the one part of Vantage that is not agent-mediated: guacd
-  connects directly, so a machine reachable only by its agent cannot be
-  consoled.
+- The target's **agent must be online**. Console traffic is relayed over the
+  agent's existing outbound connection, so the control plane never needs a route
+  to the server's address — but it does need the agent.
+- No inbound port on the target, beyond what the protocol already listens on
+  locally. A service bound only to `127.0.0.1` works, because the agent dials
+  loopback on the target itself.
 
 ## Opening a session
 
 From a server's page, choose **Console**. Then:
 
 1. The UI calls `POST /api/console/connect`, which mints a **one-time** session
-   token.
+   token. If the target's agent is not connected, this fails immediately with
+   `409 agent_offline` rather than hanging.
 2. The browser opens a WebSocket to `GET /api/console/tunnel` with that token.
 3. The server marks the token consumed atomically, so a second use cannot
    race and proxies the connection to guacd.
@@ -67,4 +70,4 @@ keystroke log. If you need that, it has to come from the target machine.
 | Connects then closes immediately | guacd unreachable check `GUACD_ADDR` and that the container is up               |
 | SSH refuses the key              | The stored key has no private half, or is not in the target's `authorized_keys` |
 | RDP fails on a fresh credential  | Credentials are consumed on open; a retry needs them entered again              |
-| Hangs at connecting              | The control plane cannot reach the target on the protocol port                  |
+| Hangs, then disconnects           | The agent never claimed the relay, nothing is listening on the protocol port on the target's own loopback address, or guacd never dialled in time. Check the audit log for `console.proxy_failed` — its reason (`agent_timeout`, `dial_refused`, `guacd_timeout`, `rejected`) names which |

proto/vantage/v1/vantage.proto

@@ -14,6 +14,7 @@ service Vantage {
   rpc ReportChecks(ReportChecksRequest)         returns (ReportChecksResponse);
   // Bidirectional stream: agent sends auth once, server pushes commands.
   rpc CommandStream(stream AgentMessage)        returns (stream ServerCommand);
+  rpc ProxyStream(stream ProxyClientMsg) returns (stream ProxyServerMsg);
 }
 
 message RegisterRequest {
@@ -180,6 +181,7 @@ message ServerCommand {
     ApplyUpdatesCmd apply_updates = 5;
     RunStepCmd      run_step      = 6;
     CleanupWorkspaceCmd cleanup_workspace = 7;
+    OpenProxyCmd open_proxy = 8;
   }
 }
 
@@ -228,3 +230,33 @@ message StepOutputChunk {
   bytes  data       = 3;
   bool   eof        = 4;
 }
+
+// OpenProxyCmd tells the agent to dial 127.0.0.1:port locally and relay that
+// connection back over a fresh ProxyStream identified by proxy_id.
+message OpenProxyCmd {
+  string proxy_id = 1;
+  uint32 port     = 2;
+}
+
+message ProxyOpen {
+  string server_id   = 1;
+  string agent_token = 2;
+  string proxy_id    = 3;
+}
+
+message ProxyClose { string reason = 1; }
+
+message ProxyClientMsg {
+  oneof payload {
+    ProxyOpen  open  = 1;   // first message only
+    bytes      data  = 2;
+    ProxyClose close = 3;
+  }
+}
+
+message ProxyServerMsg {
+  oneof payload {
+    bytes      data  = 1;
+    ProxyClose close = 2;
+  }
+}

server/internal/api/console.go

@@ -1,6 +1,8 @@
 package api
 
 import (
+	"errors"
+	"fmt"
 	"net"
 	"net/http"
 	"os"
@@ -33,6 +35,15 @@ func consoleConnect(c *gin.Context) {
 		return
 	}
 
+	if srv.Status != "active" {
+		c.JSON(http.StatusConflict, gin.H{
+			"error": "agent_offline",
+			"message": "The agent on this server is not connected. " +
+				"Console sessions are relayed by the agent, so it must be online.",
+		})
+		return
+	}
+
 	sess, err := services.CreateConsoleSession(auth.InstanceID(c), body.ServerID, body.Protocol, body.KeyID, actorFromCtx(c), c.ClientIP())
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
@@ -59,7 +70,7 @@ func consoleConnect(c *gin.Context) {
 	}
 
 	services.LogEvent(auth.InstanceID(c), "console.opened", actorFromCtx(c), srv.ServerID, "",
-		"console session opened ("+body.Protocol+")")
+		"console session opened ("+body.Protocol+", agent-relayed)")
 
 	c.JSON(http.StatusOK, gin.H{
 		"session_id": sess.SessionID,
@@ -124,7 +135,43 @@ func consoleTunnel(c *gin.Context) {
 			return
 		}
 	}
-	gp, err := services.BuildGuacParams(srv, sess.Protocol, sess.SSHUsername, privKey, passphrase, rdpUser, rdpPass)
+	targetPort, err := services.TargetPort(srv, sess.Protocol)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	relay, err := services.OpenConsoleProxy(instanceID, srv.ServerID, targetPort)
+	if err != nil {
+		if errors.Is(err, services.ErrAgentOffline) {
+			c.JSON(http.StatusConflict, gin.H{"error": "agent_offline"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not open relay"})
+		return
+	}
+	// guac.WebsocketServer.ServeHTTP returns before installing its
+	// OnDisconnect handler when the connect callback errors, which is exactly
+	// the path every relay failure this proxy introduces takes (the agent
+	// never claims it, dial_refused, guacd never dials, rejected). Emitting
+	// console.proxy_failed and ending the session here, unconditionally on
+	// teardown, is what makes those failures reach the audit log at all;
+	// OnDisconnect below only sees the rarer case of a session that was fully
+	// established and then failed.
+	defer func() {
+		relay.Close()
+		if reason := relay.Reason(); reason != "" {
+			services.LogEvent(instanceID, "console.proxy_failed", actorFromCtx(c), srv.ServerID, "",
+				fmt.Sprintf("console relay failed: %s (proxy_id=%s, port=%d)", reason, relay.ProxyID, relay.Port))
+		}
+		_ = services.EndConsoleSession(instanceID, sessionID)
+	}()
+
+	services.LogEvent(instanceID, "console.proxy_opened", actorFromCtx(c), srv.ServerID, "",
+		fmt.Sprintf("console relay opened (proxy_id=%s, port=%d)", relay.ProxyID, relay.Port))
+
+	gp, err := services.BuildGuacParams(sess.Protocol, sess.SSHUsername, privKey, passphrase,
+		rdpUser, rdpPass, relay.Host, relay.Port)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
@@ -160,9 +207,9 @@ func consoleTunnel(c *gin.Context) {
 		return guac.NewSimpleTunnel(stream), nil
 	}
 
+	// Teardown (proxy_failed audit + EndConsoleSession) lives in the deferred
+	// func above, not here: this only fires once a tunnel was actually
+	// established, and letting both paths log would double the audit event.
 	wsServer := guac.NewWebsocketServer(connect)
-	wsServer.OnDisconnect = func(id string, r *http.Request, t guac.Tunnel) {
-		_ = services.EndConsoleSession(instanceID, sessionID)
-	}
 	wsServer.ServeHTTP(c.Writer, c.Request)
 }

server/internal/grpc/pb/vantage.pb.go

@@ -123,6 +123,32 @@ type ReportChecksResponse struct{}
 
 type ApplyUpdatesCmd struct{}
 
+type OpenProxyCmd struct {
+	ProxyId string `json:"proxy_id"`
+	Port    uint32 `json:"port"`
+}
+
+type ProxyOpen struct {
+	ServerId   string `json:"server_id"`
+	AgentToken string `json:"agent_token"`
+	ProxyId    string `json:"proxy_id"`
+}
+
+type ProxyClose struct {
+	Reason string `json:"reason,omitempty"`
+}
+
+type ProxyClientMsg struct {
+	Open  *ProxyOpen  `json:"open,omitempty"`
+	Data  []byte      `json:"data,omitempty"`
+	Close *ProxyClose `json:"close,omitempty"`
+}
+
+type ProxyServerMsg struct {
+	Data  []byte      `json:"data,omitempty"`
+	Close *ProxyClose `json:"close,omitempty"`
+}
+
 type ServerCommand struct {
 	CommandId        string               `json:"command_id"`
 	GenerateKey      *GenerateKeyCmd      `json:"generate_key,omitempty"`
@@ -131,6 +157,7 @@ type ServerCommand struct {
 	ApplyUpdates     *ApplyUpdatesCmd     `json:"apply_updates,omitempty"`
 	RunStep          *RunStepCmd          `json:"run_step,omitempty"`
 	CleanupWorkspace *CleanupWorkspaceCmd `json:"cleanup_workspace,omitempty"`
+	OpenProxy        *OpenProxyCmd        `json:"open_proxy,omitempty"`
 }
 
 type CleanupWorkspaceCmd struct {
@@ -239,6 +266,55 @@ func (c *vantageCommandStreamClient) Recv() (*ServerCommand, error) {
 	return m, nil
 }
 
+type Vantage_ProxyStreamServer interface {
+	Send(*ProxyServerMsg) error
+	Recv() (*ProxyClientMsg, error)
+	grpc.ServerStream
+}
+
+type vantageProxyStreamServer struct {
+	grpc.ServerStream
+}
+
+func (s *vantageProxyStreamServer) Send(m *ProxyServerMsg) error {
+	return s.ServerStream.SendMsg(m)
+}
+
+func (s *vantageProxyStreamServer) Recv() (*ProxyClientMsg, error) {
+	m := new(ProxyClientMsg)
+	if err := s.ServerStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+type Vantage_ProxyStreamClient interface {
+	Send(*ProxyClientMsg) error
+	Recv() (*ProxyServerMsg, error)
+	CloseSend() error
+	grpc.ClientStream
+}
+
+type vantageProxyStreamClient struct {
+	grpc.ClientStream
+}
+
+func (c *vantageProxyStreamClient) Send(m *ProxyClientMsg) error {
+	return c.ClientStream.SendMsg(m)
+}
+
+func (c *vantageProxyStreamClient) Recv() (*ProxyServerMsg, error) {
+	m := new(ProxyServerMsg)
+	if err := c.ClientStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+func _Vantage_ProxyStream_Handler(srv interface{}, stream grpc.ServerStream) error {
+	return srv.(VantageServer).ProxyStream(&vantageProxyStreamServer{stream})
+}
+
 type VantageServer interface {
 	Register(context.Context, *RegisterRequest) (*RegisterResponse, error)
 	SyncKeys(context.Context, *SyncRequest) (*SyncResponse, error)
@@ -248,6 +324,7 @@ type VantageServer interface {
 	SyncMonitors(context.Context, *SyncMonitorsRequest) (*SyncMonitorsResponse, error)
 	ReportChecks(context.Context, *ReportChecksRequest) (*ReportChecksResponse, error)
 	CommandStream(Vantage_CommandStreamServer) error
+	ProxyStream(Vantage_ProxyStreamServer) error
 }
 
 type UnimplementedVantageServer struct{}
@@ -284,6 +361,10 @@ func (UnimplementedVantageServer) CommandStream(Vantage_CommandStreamServer) err
 	return status.Errorf(codes.Unimplemented, "method CommandStream not implemented")
 }
 
+func (UnimplementedVantageServer) ProxyStream(Vantage_ProxyStreamServer) error {
+	return status.Errorf(codes.Unimplemented, "method ProxyStream not implemented")
+}
+
 type VantageClient interface {
 	Register(ctx context.Context, in *RegisterRequest, opts ...grpc.CallOption) (*RegisterResponse, error)
 	SyncKeys(ctx context.Context, in *SyncRequest, opts ...grpc.CallOption) (*SyncResponse, error)
@@ -293,6 +374,7 @@ type VantageClient interface {
 	SyncMonitors(ctx context.Context, in *SyncMonitorsRequest, opts ...grpc.CallOption) (*SyncMonitorsResponse, error)
 	ReportChecks(ctx context.Context, in *ReportChecksRequest, opts ...grpc.CallOption) (*ReportChecksResponse, error)
 	CommandStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_CommandStreamClient, error)
+	ProxyStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_ProxyStreamClient, error)
 }
 
 type keyManagerClient struct {
@@ -367,6 +449,14 @@ func (c *keyManagerClient) CommandStream(ctx context.Context, opts ...grpc.CallO
 	return &vantageCommandStreamClient{stream}, nil
 }
 
+func (c *keyManagerClient) ProxyStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_ProxyStreamClient, error) {
+	stream, err := c.cc.NewStream(ctx, &Vantage_ServiceDesc.Streams[1], "/vantage.v1.Vantage/ProxyStream", opts...)
+	if err != nil {
+		return nil, err
+	}
+	return &vantageProxyStreamClient{stream}, nil
+}
+
 func RegisterVantageServer(s grpc.ServiceRegistrar, srv VantageServer) {
 	s.RegisterService(&Vantage_ServiceDesc, srv)
 }
@@ -390,6 +480,12 @@ var Vantage_ServiceDesc = grpc.ServiceDesc{
 			ServerStreams: true,
 			ClientStreams: true,
 		},
+		{
+			StreamName:    "ProxyStream",
+			Handler:       _Vantage_ProxyStream_Handler,
+			ServerStreams: true,
+			ClientStreams: true,
+		},
 	},
 	Metadata: "vantage/v1/vantage.proto",
 }

server/internal/grpc/pb/vantage_pb_test.go

@@ -0,0 +1,39 @@
+package pb
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestProxyClientMsgRoundTrip(t *testing.T) {
+	in := &ProxyClientMsg{Data: []byte{0x00, 0xff, 0x10}}
+	raw, err := json.Marshal(in)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	var out ProxyClientMsg
+	if err := json.Unmarshal(raw, &out); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if string(out.Data) != string(in.Data) {
+		t.Fatalf("data mismatch: got %v want %v", out.Data, in.Data)
+	}
+	if out.Open != nil || out.Close != nil {
+		t.Fatalf("empty oneof fields should stay nil, got open=%v close=%v", out.Open, out.Close)
+	}
+}
+
+func TestOpenProxyCmdOnServerCommand(t *testing.T) {
+	cmd := &ServerCommand{CommandId: "c1", OpenProxy: &OpenProxyCmd{ProxyId: "p1", Port: 22}}
+	raw, err := json.Marshal(cmd)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	var out ServerCommand
+	if err := json.Unmarshal(raw, &out); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if out.OpenProxy == nil || out.OpenProxy.ProxyId != "p1" || out.OpenProxy.Port != 22 {
+		t.Fatalf("open_proxy did not round-trip: %+v", out.OpenProxy)
+	}
+}

server/internal/grpc/proxystream.go

@@ -0,0 +1,51 @@
+package grpcserver
+
+import (
+	"log"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/grpc/pb"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/proxy"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// ProxyStream carries one console TCP connection. The agent opens it after
+// dialling its own loopback address, and authenticates with the same agent
+// token as the command stream plus the single-use proxy_id it was handed.
+func (s *vantageServer) ProxyStream(stream pb.Vantage_ProxyStreamServer) error {
+	msg, err := stream.Recv()
+	if err != nil {
+		return status.Errorf(codes.InvalidArgument, "expected initial open message: %v", err)
+	}
+	if msg.Open == nil {
+		return status.Error(codes.InvalidArgument, "first message must be open")
+	}
+
+	srv, err := services.ValidateAgentToken(msg.Open.ServerId, msg.Open.AgentToken)
+	if err != nil {
+		// Deliberately identical to the claim-failure response below: a bad
+		// token, an unknown proxy_id, and a proxy_id belonging to another
+		// instance/server must be indistinguishable to the caller.
+		log.Printf("proxy %s (server %s): invalid agent token", msg.Open.ProxyId, msg.Open.ServerId)
+		return status.Error(codes.PermissionDenied, "proxy session unavailable")
+	}
+
+	if err := serveProxy(proxy.Default, msg.Open, srv.InstanceID, stream); err != nil {
+		// The reason is deliberately not returned to the agent: an unknown and a
+		// foreign proxy_id must be indistinguishable.
+		log.Printf("proxy %s (server %s): %v", msg.Open.ProxyId, msg.Open.ServerId, err)
+		return status.Error(codes.PermissionDenied, "proxy session unavailable")
+	}
+	return nil
+}
+
+// serveProxy claims the pending session and relays it. Split out from the gRPC
+// method so the authorisation matrix is testable without a real stream.
+func serveProxy(reg *proxy.Registry, open *pb.ProxyOpen, instanceID string, stream proxy.AgentStream) error {
+	entry, err := reg.Claim(instanceID, open.ServerId, open.ProxyId)
+	if err != nil {
+		return err
+	}
+	return entry.Session.Serve(stream)
+}

server/internal/proxy/registry.go

@@ -0,0 +1,80 @@
+// Package proxy relays console TCP traffic between guacd and a managed server's
+// agent. The agent dials only its own loopback address; the port is the single
+// value it takes from the control plane.
+package proxy
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"sync"
+)
+
+var (
+	ErrNotFound  = errors.New("proxy session not found")
+	ErrForbidden = errors.New("proxy session belongs to another server")
+)
+
+// NewID returns a 32-byte random identifier as hex. It is the only credential
+// tying an incoming ProxyStream to a pending console session.
+func NewID() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}
+
+type Entry struct {
+	ProxyID    string
+	InstanceID string
+	ServerID   string
+	Session    *Session
+}
+
+type Registry struct {
+	mu      sync.Mutex
+	entries map[string]*Entry
+}
+
+func NewRegistry() *Registry {
+	return &Registry{entries: make(map[string]*Entry)}
+}
+
+var Default = NewRegistry()
+
+func (r *Registry) Add(e *Entry) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.entries[e.ProxyID] = e
+}
+
+// Claim removes and returns the entry. It is single-use: a second claim on the
+// same proxy_id gets ErrNotFound. A claim whose instance or server does not
+// match leaves the entry in place and gets ErrForbidden.
+func (r *Registry) Claim(instanceID, serverID, proxyID string) (*Entry, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	e, ok := r.entries[proxyID]
+	if !ok {
+		return nil, ErrNotFound
+	}
+	if e.InstanceID != instanceID || e.ServerID != serverID {
+		return nil, ErrForbidden
+	}
+	delete(r.entries, proxyID)
+	return e, nil
+}
+
+func (r *Registry) Remove(proxyID string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	delete(r.entries, proxyID)
+}
+
+func (r *Registry) Len() int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return len(r.entries)
+}

server/internal/proxy/session.go

@@ -0,0 +1,249 @@
+package proxy
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"os"
+	"sync"
+	"time"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/grpc/pb"
+)
+
+const (
+	chunkSize         = 32 * 1024
+	rendezvousTimeout = 10 * time.Second
+)
+
+// AgentStream is the server's half of a ProxyStream. It is an interface so the
+// relay can be tested without gRPC.
+type AgentStream interface {
+	Send(*pb.ProxyServerMsg) error
+	Recv() (*pb.ProxyClientMsg, error)
+}
+
+// Session owns one ephemeral listener and relays the single connection that
+// arrives on it to an agent stream.
+type Session struct {
+	listener net.Listener
+	allowed  []string
+	timeout  time.Duration
+
+	once    sync.Once
+	mu      sync.Mutex
+	reason  string
+	conn    net.Conn
+	closing bool
+
+	rendezvous *time.Timer
+}
+
+// NewSession binds an ephemeral port on listenHost. allowed is the set of IPs
+// permitted to connect; an empty set allows any, which is the degraded case
+// when guacd's host could not be resolved.
+//
+// A watchdog is armed immediately: if the agent never opens its ProxyStream
+// and calls Serve, nothing else would ever bound how long the listener (and
+// the registry entry that references it) stays open. Serve cancels it once
+// entered and re-arms the same deadline for the accept wait.
+func NewSession(listenHost string, allowed []string) (*Session, error) {
+	ln, err := net.Listen("tcp", net.JoinHostPort(listenHost, "0"))
+	if err != nil {
+		return nil, fmt.Errorf("bind relay listener: %w", err)
+	}
+	s := &Session{listener: ln, allowed: allowed, timeout: rendezvousTimeout}
+	s.rendezvous = time.AfterFunc(rendezvousTimeout, func() {
+		s.Close("agent_timeout")
+	})
+	return s, nil
+}
+
+func (s *Session) Port() int {
+	return s.listener.Addr().(*net.TCPAddr).Port
+}
+
+// Reason reports why the session ended, empty if it ended cleanly.
+func (s *Session) Reason() string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.reason
+}
+
+// setReason records r as the session's failure reason, first write wins. It is
+// a no-op once a deliberate teardown (Close) has begun: a local Close closing
+// the conn out from under the relay goroutines produces exactly the kind of
+// error (net.ErrClosed, a broken pipe on write, ...) that looks like a remote
+// failure but is not one, and must not overwrite — or race to set — the real
+// reason, or invent one where a clean local close has none.
+func (s *Session) setReason(r string) {
+	s.mu.Lock()
+	if s.reason == "" && !s.closing {
+		s.reason = r
+	}
+	s.mu.Unlock()
+}
+
+// Close tears the session down once. A non-empty reason is recorded only if no
+// reason has been recorded already, and only before teardown begins. It closes
+// both the listener and, if a connection has already been accepted, that
+// connection too — an unconditional kill for the whole relay chain regardless
+// of which stage it is in.
+func (s *Session) Close(reason string) {
+	if reason != "" {
+		s.setReason(reason)
+	}
+	s.once.Do(func() {
+		// Recorded before anything is actually closed: the reader/writer
+		// goroutines in relay() call setReason from the errors this Close
+		// itself is about to cause (a closed conn, a closed stream), and
+		// those must be recognised as teardown noise, not a genuine failure.
+		s.mu.Lock()
+		s.closing = true
+		conn := s.conn
+		s.mu.Unlock()
+
+		if s.rendezvous != nil {
+			s.rendezvous.Stop()
+		}
+		_ = s.listener.Close()
+		if conn != nil {
+			_ = conn.Close()
+		}
+	})
+}
+
+func (s *Session) setConn(conn net.Conn) {
+	s.mu.Lock()
+	s.conn = conn
+	s.mu.Unlock()
+}
+
+// Serve accepts exactly one connection, verifies its source, and relays until
+// either side ends. It always closes the listener before returning.
+func (s *Session) Serve(stream AgentStream) error {
+	defer s.Close("")
+
+	// The agent has claimed the session and opened its stream, so the
+	// unclaimed-rendezvous watchdog no longer applies; the accept deadline set
+	// just below takes over for the claimed case.
+	if s.rendezvous != nil {
+		s.rendezvous.Stop()
+	}
+
+	if l, ok := s.listener.(*net.TCPListener); ok {
+		_ = l.SetDeadline(time.Now().Add(s.timeout))
+	}
+
+	// Accept until a connection from an allowed source arrives or the
+	// rendezvous deadline (set once, above) expires. A rejected connection is
+	// closed and the loop retries within the same deadline; the listener is
+	// only closed once we have a valid connection, the deadline expires, or
+	// Accept fails for a genuine (non-timeout) reason.
+	for {
+		conn, err := s.listener.Accept()
+		if err != nil {
+			var netErr net.Error
+			if errors.Is(err, os.ErrDeadlineExceeded) || (errors.As(err, &netErr) && netErr.Timeout()) {
+				s.setReason("guacd_timeout")
+			} else {
+				s.setReason("accept_failed")
+			}
+			return fmt.Errorf("waiting for guacd: %w", err)
+		}
+
+		if !allowedRemote(conn.RemoteAddr().String(), s.allowed) {
+			_ = conn.Close()
+			continue
+		}
+
+		// One connection only: nothing else may claim this port. Store the
+		// conn first so a concurrent external Close (e.g. the browser tab
+		// closing) can reach it via the sync.Once teardown; then close just
+		// the listener directly (not through Close, which would also close
+		// the conn we are about to relay). The deferred s.Close("") above
+		// performs the real one-shot teardown, including this conn, once
+		// relay returns.
+		s.setConn(conn)
+		_ = s.listener.Close()
+
+		return s.relay(conn, stream)
+	}
+}
+
+func (s *Session) relay(conn net.Conn, stream AgentStream) error {
+	errCh := make(chan error, 2)
+
+	// guacd -> agent
+	go func() {
+		buf := make([]byte, chunkSize)
+		for {
+			n, err := conn.Read(buf)
+			if n > 0 {
+				chunk := make([]byte, n)
+				copy(chunk, buf[:n])
+				if sendErr := stream.Send(&pb.ProxyServerMsg{Data: chunk}); sendErr != nil {
+					errCh <- sendErr
+					return
+				}
+			}
+			if err != nil {
+				if !errors.Is(err, io.EOF) {
+					s.setReason("guacd_read_error")
+				}
+				errCh <- err
+				return
+			}
+		}
+	}()
+
+	// agent -> guacd
+	go func() {
+		for {
+			msg, err := stream.Recv()
+			if err != nil {
+				errCh <- err
+				return
+			}
+			if msg.Close != nil {
+				s.setReason(msg.Close.Reason)
+				errCh <- fmt.Errorf("agent closed relay: %s", msg.Close.Reason)
+				return
+			}
+			if len(msg.Data) > 0 {
+				if _, err := conn.Write(msg.Data); err != nil {
+					errCh <- err
+					return
+				}
+			}
+		}
+	}()
+
+	err := <-errCh
+	_ = conn.Close()
+	if errors.Is(err, io.EOF) {
+		return nil
+	}
+	return err
+}
+
+// allowedRemote reports whether remote (a host:port string) is in allowed. An
+// empty allowed list permits anything.
+func allowedRemote(remote string, allowed []string) bool {
+	host, _, err := net.SplitHostPort(remote)
+	if err != nil {
+		log.Printf("proxy: unparseable remote address %q", remote)
+		return false
+	}
+	if len(allowed) == 0 {
+		return true
+	}
+	for _, a := range allowed {
+		if a == host {
+			return true
+		}
+	}
+	return false
+}

server/internal/services/console.go

@@ -77,20 +77,37 @@ type GuacParams struct {
 	Params   map[string]string
 }
 
-func portOr(v, def int) string {
+func portOr(v, def int) int {
 	if v == 0 {
-		v = def
+		return def
 	}
-	return strconv.Itoa(v)
+	return v
 }
 
-func BuildGuacParams(srv *models.Server, protocol, sshUser, privateKey, passphrase, rdpUser, rdpPass string) (*GuacParams, error) {
-	host := srv.IPAddress
+// TargetPort is the port on the managed server that the agent will dial on its
+// own loopback address.
+func TargetPort(srv *models.Server, protocol string) (int, error) {
+	switch protocol {
+	case "ssh":
+		return portOr(srv.SSHPort, 22), nil
+	case "rdp":
+		return portOr(srv.RDPPort, 3389), nil
+	case "vnc":
+		return 5900, nil
+	default:
+		return 0, fmt.Errorf("unsupported protocol %q", protocol)
+	}
+}
+
+// BuildGuacParams points guacd at the relay listener, never at the managed
+// server: on a cloud deployment the server's address is not routable from here.
+func BuildGuacParams(protocol, sshUser, privateKey, passphrase, rdpUser, rdpPass, relayHost string, relayPort int) (*GuacParams, error) {
+	port := strconv.Itoa(relayPort)
 	switch protocol {
 	case "ssh":
 		p := map[string]string{
-			"hostname": host,
-			"port":     portOr(srv.SSHPort, 22),
+			"hostname": relayHost,
+			"port":     port,
 		}
 		if sshUser == "" {
 			sshUser = "root"
@@ -105,8 +122,8 @@ func BuildGuacParams(srv *models.Server, protocol, sshUser, privateKey, passphra
 		return &GuacParams{Protocol: "ssh", Params: p}, nil
 	case "rdp":
 		return &GuacParams{Protocol: "rdp", Params: map[string]string{
-			"hostname":    host,
-			"port":        portOr(srv.RDPPort, 3389),
+			"hostname":    relayHost,
+			"port":        port,
 			"username":    rdpUser,
 			"password":    rdpPass,
 			"security":    "any",
@@ -114,8 +131,8 @@ func BuildGuacParams(srv *models.Server, protocol, sshUser, privateKey, passphra
 		}}, nil
 	case "vnc":
 		return &GuacParams{Protocol: "vnc", Params: map[string]string{
-			"hostname": host,
-			"port":     "5900",
+			"hostname": relayHost,
+			"port":     port,
 			"password": rdpPass,
 		}}, nil
 	default:

server/internal/services/consoleproxy.go

@@ -0,0 +1,122 @@
+package services
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"net"
+	"os"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/grpc/pb"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/proxy"
+)
+
+// ErrAgentOffline means the console cannot be opened because the target's agent
+// is not on the command stream. Every console session is relayed by the agent,
+// so this is fatal rather than a degraded mode.
+var ErrAgentOffline = errors.New("agent is not connected")
+
+// ConsoleProxy is a pending relay: a bound listener guacd can dial and a
+// dispatched command telling the agent to meet it.
+type ConsoleProxy struct {
+	ProxyID string
+	Host    string
+	Port    int
+
+	session *proxy.Session
+}
+
+func (c *ConsoleProxy) Close() {
+	proxy.Default.Remove(c.ProxyID)
+	c.session.Close("")
+}
+
+func (c *ConsoleProxy) Reason() string { return c.session.Reason() }
+
+func proxyListenHost() string {
+	if v := os.Getenv("PROXY_LISTEN_HOST"); v != "" {
+		return v
+	}
+	return "0.0.0.0"
+}
+
+func proxyAdvertiseHost() string {
+	if v := os.Getenv("PROXY_ADVERTISE_HOST"); v != "" {
+		return v
+	}
+	return "server"
+}
+
+func guacdAddr() string {
+	if v := os.Getenv("GUACD_ADDR"); v != "" {
+		return v
+	}
+	return "guacd:4822"
+}
+
+// guacdHosts resolves guacd's address to the IPs allowed to claim a relay
+// listener. An unresolvable host yields an empty set, which allows any source:
+// refusing everything would take the console down entirely, so the narrower
+// protections (ephemeral port, 10s window, single accept) carry it instead.
+func guacdHosts(addr string) []string {
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil {
+		host = addr
+	}
+	if ip := net.ParseIP(host); ip != nil {
+		return []string{ip.String()}
+	}
+	ips, err := net.LookupHost(host)
+	if err != nil {
+		log.Printf("proxy: cannot resolve guacd host %q, allowing any relay source: %v", host, err)
+		return nil
+	}
+	return ips
+}
+
+// DispatchOpenProxy tells the agent to dial its own loopback on port and relay
+// it back under proxyID.
+func DispatchOpenProxy(serverID, proxyID string, port uint32) error {
+	return Dispatcher.dispatch(serverID, &pb.ServerCommand{
+		CommandId: proxyID,
+		OpenProxy: &pb.OpenProxyCmd{ProxyId: proxyID, Port: port},
+	})
+}
+
+// OpenConsoleProxy binds a relay listener, registers it, and asks the agent to
+// connect. The caller must Close the result.
+func OpenConsoleProxy(instanceID, serverID string, targetPort int) (*ConsoleProxy, error) {
+	if !Dispatcher.IsConnected(serverID) {
+		return nil, ErrAgentOffline
+	}
+
+	proxyID, err := proxy.NewID()
+	if err != nil {
+		return nil, fmt.Errorf("generate proxy id: %w", err)
+	}
+
+	sess, err := proxy.NewSession(proxyListenHost(), guacdHosts(guacdAddr()))
+	if err != nil {
+		return nil, err
+	}
+
+	proxy.Default.Add(&proxy.Entry{
+		ProxyID:    proxyID,
+		InstanceID: instanceID,
+		ServerID:   serverID,
+		Session:    sess,
+	})
+
+	if err := DispatchOpenProxy(serverID, proxyID, uint32(targetPort)); err != nil {
+		proxy.Default.Remove(proxyID)
+		sess.Close("dispatch_failed")
+		return nil, err
+	}
+
+	return &ConsoleProxy{
+		ProxyID: proxyID,
+		Host:    proxyAdvertiseHost(),
+		Port:    sess.Port(),
+		session: sess,
+	}, nil
+}