fix: Guacd connection ip

InitRedis now takes a username and password, read from REDIS_USERNAME and
REDIS_PASSWORD, matching what admin has always done. Both empty keeps an
unauthenticated Redis working; a password with an empty username is what a
legacy requirepass instance needs, since go-redis then sends AUTH with one
argument instead of two.

This is what lets a Kubernetes install point at a managed Redis instead of
the bundled one.

.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "C:/Python314/Scripts/graphify.EXE hook-guard search"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "C:/Python314/Scripts/graphify.EXE hook-guard read"
+          }
+        ]
+      }
+    ]
+  }
+}

.gitattributes

@@ -0,0 +1 @@
+graphify-out/graph.json merge=graphify

.gitea/workflows/chart-release.yml

@@ -0,0 +1,221 @@
+name: Chart Release
+
+on:
+    # Every push that touches the chart is validated. Publishing is separate and
+    # deliberate: a chart version is immutable in the registry once pushed, so
+    # it must come from a tag someone chose, not from whatever landed on main.
+    # No `paths` filter on push, deliberately. A paths filter applies to tag
+    # pushes too, so tagging a commit that happened not to touch the chart
+    # would skip the publish entirely — a release that silently does nothing.
+    # Validation is seconds of helm rendering; running it on every push to main
+    # is cheaper than that failure mode.
+    push:
+        branches:
+            - main
+        tags:
+            - "chart/v*"
+    pull_request:
+        paths:
+            - "deploy/chart/**"
+    workflow_dispatch:
+
+env:
+    CHART_DIR: deploy/chart/vantage
+    HELM_VERSION: v3.16.3
+
+jobs:
+    chart:
+        runs-on: ubuntu-docker
+        container: alpine:3.21
+        steps:
+            # git for actions/checkout, curl for both the Helm download and the
+            # registry upload, tar because the Helm tarball is not self-extracting.
+            - name: Setup
+              run: apk add --no-cache bash curl git tar nodejs npm
+
+            - name: Install Helm
+              run: |
+                  set -eu
+                  curl -fsSL "https://get.helm.sh/helm-${HELM_VERSION}-linux-amd64.tar.gz" \
+                    | tar -xz -C /tmp linux-amd64/helm
+                  mv /tmp/linux-amd64/helm /usr/local/bin/helm
+                  helm version --short
+
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Lint
+              run: helm lint "$CHART_DIR"
+
+            # Rendering is the real test. `helm lint` accepts a chart whose
+            # templates fail to execute, and every guard in this chart is a
+            # template `fail` that only fires during rendering.
+            - name: Render default values
+              run: helm template test "$CHART_DIR" > /dev/null
+
+            - name: Render a multi-replica install
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set server.replicaCount=3 \
+                    --set web.replicaCount=3 > /dev/null
+
+            # The reaper deletes whole instances, so "does this env appear only
+            # in cloud mode" is worth asserting rather than eyeballing.
+            - name: Check the reaper is cloud-only
+              run: |
+                  set -eu
+                  if helm template test "$CHART_DIR" | grep -q FREE_INSTANCE_REAP_AFTER; then
+                      echo "FREE_INSTANCE_REAP_AFTER is set on a self-hosted render"
+                      exit 1
+                  fi
+                  if ! helm template test "$CHART_DIR" \
+                        --set server.env.deploymentType=cloud \
+                      | grep -q FREE_INSTANCE_REAP_AFTER; then
+                      echo "FREE_INSTANCE_REAP_AFTER is missing from a cloud render"
+                      exit 1
+                  fi
+                  echo "ok: reaper configured in cloud mode only"
+
+            - name: Render against external Redis and MongoDB
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set redis.enabled=false \
+                    --set redis.addr=redis.example.com:6379 \
+                    --set mongo.enabled=false \
+                    --set server.env.mongoUri=mongodb://mongo.example.com:27017/vantage > /dev/null
+
+            - name: Render with the Traefik ingress
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set ingress.enabled=true \
+                    --set ingress.web.host=vantage.example.com \
+                    --set ingress.grpc.host=agents.example.com \
+                    --set ingress.tls.certResolver=letsencrypt \
+                    --set server.env.grpcHost=agents.example.com:443 > /dev/null
+
+            # The shape the cloud deployment actually uses: a wildcard tenant
+            # namespace, /api and /auth routed at the edge, and no apex — that
+            # belongs to the marketing site, which this chart does not deploy.
+            - name: Render a wildcard host with edge-routed API paths
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set ingress.enabled=true \
+                    --set 'ingress.web.host=*.vantage.example.com' \
+                    --set ingress.api.enabled=true \
+                    --set ingress.grpc.host=agents.example.com \
+                    --set server.env.grpcHost=agents.example.com:443 \
+                    --set ingress.tls.secretName=vantage-tls \
+                    --set ingress.tls.grpcSecretName=agents-tls > /dev/null
+
+            # The guards are load-bearing, so their absence is a regression the
+            # same way a broken render is. Each of these must fail.
+            - name: Check the guards still refuse bad values
+              run: |
+                  set -eu
+
+                  refuses() {
+                      desc="$1"; shift
+                      if helm template test "$CHART_DIR" "$@" > /dev/null 2>&1; then
+                          echo "GUARD MISSING: $desc was accepted"
+                          exit 1
+                      fi
+                      echo "ok: refused $desc"
+                  }
+
+                  refuses "mongo disabled with an in-chart URI" \
+                      --set mongo.enabled=false
+                  refuses "redis disabled with no external address" \
+                      --set redis.enabled=false
+                  refuses "multiple replicas on a ReadWriteOnce volume" \
+                      --set server.replicaCount=2 --set server.persistence.enabled=true
+                  refuses "ingress with no web host" \
+                      --set ingress.enabled=true
+                  refuses "edge-routed API with an empty path list" \
+                      --set ingress.enabled=true \
+                      --set ingress.web.host=vantage.example.com \
+                      --set ingress.grpc.enabled=false \
+                      --set ingress.api.enabled=true \
+                      --set 'ingress.api.paths=null'
+                  refuses "gRPC ingress with no host" \
+                      --set ingress.enabled=true \
+                      --set ingress.web.host=vantage.example.com \
+                      --set server.env.grpcHost=agents.example.com:443
+                  refuses "gRPC ingress while grpcHost is still in-cluster" \
+                      --set ingress.enabled=true \
+                      --set ingress.web.host=vantage.example.com \
+                      --set ingress.grpc.host=agents.example.com
+
+            - name: Read the chart version
+              id: chart
+              run: |
+                  set -eu
+                  VERSION="$(grep '^version:' "$CHART_DIR/Chart.yaml" | awk '{print $2}')"
+                  echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+                  echo "chart version is $VERSION"
+
+            # Chart.yaml is the source of truth for the version; the tag only
+            # says "publish this one". A mismatch is a mistake worth stopping
+            # for — the alternative is stamping the tag over Chart.yaml, which
+            # leaves the repository disagreeing with what was published.
+            - name: Check the tag matches Chart.yaml
+              if: startsWith(github.ref, 'refs/tags/chart/v')
+              run: |
+                  set -eu
+                  TAG_VERSION="${GITHUB_REF_NAME#chart/v}"
+                  CHART_VERSION="${{ steps.chart.outputs.version }}"
+                  if [ "$TAG_VERSION" != "$CHART_VERSION" ]; then
+                      echo "tag chart/v$TAG_VERSION does not match Chart.yaml version $CHART_VERSION"
+                      echo "bump version: in $CHART_DIR/Chart.yaml, or retag."
+                      exit 1
+                  fi
+
+            - name: Package
+              run: |
+                  set -eu
+                  mkdir -p dist
+                  helm package "$CHART_DIR" --destination dist
+                  ls -l dist
+
+            - name: Publish to the Gitea chart registry
+              if: startsWith(github.ref, 'refs/tags/chart/v')
+              env:
+                  # github.server_url is this Gitea instance, so the registry
+                  # host needs no variable of its own and cannot drift from it.
+                  REGISTRY: ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/helm/api/charts
+                  # The same pair server-deploy.yml uses for `docker login`.
+                  # RELEASE_TOKEN, not REGISTRY_PASSWORD: the latter is named in
+                  # the docs but set by no workflow, and an unset secret becomes
+                  # an empty password, which Gitea reports as "Failed to
+                  # authenticate user" rather than as a missing credential.
+                  REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+                  REGISTRY_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+                  CHART_VERSION: ${{ steps.chart.outputs.version }}
+              run: |
+                  set -eu
+                  PKG="dist/vantage-${CHART_VERSION}.tgz"
+                  test -f "$PKG"
+
+                  # Checked explicitly, because the failure it prevents is a
+                  # 401 that looks like a permissions problem on the token that
+                  # was never sent.
+                  if [ -z "${REGISTRY_USER}" ] || [ -z "${REGISTRY_TOKEN}" ]; then
+                      echo "REGISTRY_USER or RELEASE_TOKEN is not set on this repository."
+                      echo "RELEASE_TOKEN needs the write:package scope to publish a chart."
+                      exit 1
+                  fi
+
+                  echo "publishing to ${REGISTRY} as ${REGISTRY_USER}"
+
+                  # --fail-with-body so an HTTP error is a failed step with the
+                  # server's explanation, rather than a green run that published
+                  # nothing. A repeated version is rejected by the registry;
+                  # that is the intended behaviour, not something to retry past.
+                  curl --fail-with-body -sS \
+                       --user "${REGISTRY_USER}:${REGISTRY_TOKEN}" \
+                       -X POST \
+                       --upload-file "$PKG" \
+                       "$REGISTRY"
+
+                  echo "published vantage ${CHART_VERSION}"
+                  echo "  helm repo add vantage ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/helm"
+                  echo "  helm install vantage vantage/vantage --version ${CHART_VERSION}"

.gitea/workflows/server-deploy.yml

@@ -77,15 +77,17 @@ jobs:
                   # generated pb is committed under server/, but a proto change
                   # that someone regenerates in the same push should not depend
                   # on that ordering.
-                  flag server    '^(server/|shared/|proto/|go\.work)'
+                  flag server    '^(server/|shared/|proto/|default_steps/|go\.work)'
                   flag sitesvc   '^(sitesvc/|shared/|go\.work)'
                   flag admin     '^(admin/|shared/|go\.work)'
 
-                  # The three Next images use their own directory as the build
-                  # context, so nothing outside it can affect them.
+                  # The three Next images and the docs site use their own
+                  # directory as the build context, so nothing outside it can
+                  # affect them.
                   flag web       '^web/'
                   flag site      '^site/'
                   flag adminsite '^adminsite/'
+                  flag docsite   '^docsite/'
 
             - name: Log in to registry
               run: |
@@ -106,7 +108,6 @@ jobs:
               run: |
                   IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/web:latest"
                   docker build \
-                    --build-arg NEXT_PUBLIC_API_URL="${{ vars.API_URL }}" \
                     --build-arg NEXT_PUBLIC_HQ_URL="${{ vars.HQ_URL }}" \
                     -t "$IMAGE" \
                     -f web/Dockerfile web/
@@ -149,6 +150,18 @@ jobs:
                     --build-arg NEXT_PUBLIC_ADMIN_ENV="${{ vars.ADMIN_ENV }}" \
                     --build-arg NEXT_PUBLIC_PADDLE_CLIENT_TOKEN="${{ vars.PADDLE_CLIENT_TOKEN }}" \
                     --build-arg NEXT_PUBLIC_PADDLE_ENV="${{ vars.PADDLE_ENV }}" \
+                    --build-arg NEXT_PUBLIC_SITE_URL="${{ vars.SITE_URL }}" \
                     -t "$IMAGE" \
                     -f adminsite/Dockerfile adminsite/
                   docker push "$IMAGE"
+
+            - name: Build and push docsite image
+              if: steps.changed.outputs.docsite == 'true'
+              run: |
+                  IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/docsite:latest"
+                  # DOCS_BASE_URL must match the proxy location that routes to
+                  # this container and the directory the image serves from.
+                  docker build \
+                    -t "$IMAGE" \
+                    -f docsite/Dockerfile docsite/
+                  docker push "$IMAGE"

.gitignore

@@ -3,6 +3,7 @@ dist
 build
 .env
 .env.bck
+.env.live
 docs/*
 !docs/superpowers/
 .superpowers
@@ -11,4 +12,6 @@ installer/*.msi
 installer/nssm.zip
 installer/checksums-msi.txt
 .next
-*.tsbuildinfo
+*.tsbuildinfo
+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

adminsite/Dockerfile

@@ -26,6 +26,11 @@ ENV NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=$NEXT_PUBLIC_PADDLE_CLIENT_TOKEN
 ARG NEXT_PUBLIC_PADDLE_ENV=sandbox
 ENV NEXT_PUBLIC_PADDLE_ENV=$NEXT_PUBLIC_PADDLE_ENV
 
+# Marketing site origin. Signup lives there (/start), not here; empty renders no
+# link at all rather than one that 404s.
+ARG NEXT_PUBLIC_SITE_URL=
+ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
+
 RUN npm run build
 
 FROM node:26-alpine AS runner

adminsite/app/layout.tsx

@@ -10,7 +10,7 @@ export const metadata: Metadata = {
 
 /*
  * The masthead deliberately does NOT live here. It belongs to the authenticated
- * layouts, so /login, /signup, /verify and /accept-invite stop rendering a bar
+ * layouts, so /login, /verify and /accept-invite stop rendering a bar
  * whose navigation and account menu they cannot use.
  */
 export default function RootLayout({ children }: { children: React.ReactNode }) {

adminsite/app/login/page.tsx

@@ -2,12 +2,13 @@
 
 import { useRouter } from "next/navigation";
 import { useState } from "react";
-import Link from "next/link";
 import { API_BASE, ApiError, NotConnected, api } from "@/lib/api";
 import { NotConnectedPanel } from "@/components/NotConnected";
 import { Button } from "@/components/Button";
 import { Field } from "@/components/Field";
 
+const SITE_URL = (process.env.NEXT_PUBLIC_SITE_URL ?? "").replace(/\/$/, "");
+
 export default function LoginPage() {
     const router = useRouter();
     const [email, setEmail] = useState("");
@@ -44,46 +45,75 @@ export default function LoginPage() {
 
     return (
         <Main>
-            <h1 className="text-3xl">Sign in</h1>
-            <form onSubmit={submit} className="mt-6 grid gap-4">
-                <Field
-                    label="Email"
-                    type="email"
-                    autoComplete="username"
-                    required
-                    value={email}
-                    onChange={(e) => setEmail(e.target.value)}
-                />
-                <Field
-                    label="Password"
-                    type="password"
-                    autoComplete="current-password"
-                    required
-                    value={password}
-                    onChange={(e) => setPassword(e.target.value)}
-                    error={error ?? undefined}
-                />
-                <label className="flex items-center gap-2 text-[0.82rem] text-ink-2">
-                    <input
-                        type="checkbox"
-                        checked={staff}
-                        onChange={(e) => setStaff(e.target.checked)}
+            {/* The masthead's lockup, unlinked: there is nowhere to go yet. */}
+            <div className="mb-7 flex flex-col items-center gap-2 text-center">
+                <span className="flex items-baseline gap-2 text-[1.5rem] font-extrabold tracking-[-0.02em]">
+                    Vantage
+                    <span className="font-mono text-[0.78rem] font-normal uppercase tracking-[0.14em] text-ink-3">
+                        HQ
+                    </span>
+                </span>
+                <h1 className="text-[1.16rem]">Sign in</h1>
+                <p className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
+                    Licences · instances · billing
+                </p>
+            </div>
+
+            <div className="rounded border border-rule bg-panel p-6 shadow-[var(--shadow)]">
+                <form onSubmit={submit} className="grid gap-4">
+                    <Field
+                        label="Email"
+                        type="email"
+                        autoComplete="username"
+                        required
+                        value={email}
+                        onChange={(e) => setEmail(e.target.value)}
                     />
-                    I work at Vantage
-                </label>
-                <div className="flex flex-wrap items-center gap-3">
-                    <Button type="submit" disabled={busy}>
+                    <Field
+                        label="Password"
+                        type="password"
+                        autoComplete="current-password"
+                        required
+                        value={password}
+                        onChange={(e) => setPassword(e.target.value)}
+                        error={error ?? undefined}
+                    />
+                    <label className="flex items-center gap-2 text-[0.82rem] text-ink-2">
+                        <input
+                            type="checkbox"
+                            checked={staff}
+                            onChange={(e) => setStaff(e.target.checked)}
+                            className="accent-[var(--accent)]"
+                        />
+                        I work at Vantage
+                    </label>
+                    <Button type="submit" disabled={busy} className="w-full justify-center">
                         {busy ? "Signing in…" : "Sign in"}
                     </Button>
-                    <Link href="/signup" className="text-[0.82rem] text-accent underline">
-                        Create an account for a self-hosted licence
-                    </Link>
-                </div>
-            </form>
+                </form>
+
+                {SITE_URL && (
+                    <>
+                        <div className="my-5 h-px bg-rule-soft" />
+
+                        {/* Signup lives on the marketing site's /start, not here. */}
+                        <p className="text-center text-[0.82rem] text-ink-3">
+                            No account?{" "}
+                            <a href={`${SITE_URL}/start`} className="text-accent underline">
+                                Create one
+                            </a>
+                        </p>
+                    </>
+                )}
+            </div>
         </Main>
     );
 }
 
 function Main({ children }: { children: React.ReactNode }) {
-    return <main className="mx-auto max-w-rail px-5 py-12">{children}</main>;
+    return (
+        <main className="mx-auto flex min-h-screen w-full max-w-[26rem] flex-col justify-center px-5 py-12">
+            {children}
+        </main>
+    );
 }

adminsite/app/signup/page.tsx

@@ -1,92 +0,0 @@
-"use client";
-
-import { useState } from "react";
-import { ApiError, NotConnected, api } from "@/lib/api";
-import { Button } from "@/components/Button";
-import { Field } from "@/components/Field";
-
-export default function SignupPage() {
-    const [form, setForm] = useState({ name: "", email: "", password: "", website: "" });
-    const [state, setState] = useState<"idle" | "busy" | "sent">("idle");
-    const [error, setError] = useState<string | null>(null);
-
-    async function submit(e: React.FormEvent) {
-        e.preventDefault();
-        setState("busy");
-        setError(null);
-        try {
-            await api.signup(form);
-            setState("sent");
-        } catch (err) {
-            setState("idle");
-            setError(
-                err instanceof NotConnected
-                    ? "The licensing service is not reachable from this page."
-                    : err instanceof ApiError
-                      ? err.message
-                      : "Could not create the account. Try again.",
-            );
-        }
-    }
-
-    return (
-        <main className="mx-auto max-w-rail px-5 py-12">
-            {state === "sent" ? (
-                <div className="grid max-w-xl gap-3">
-                    <h1 className="text-3xl">Check your email</h1>
-                    <p className="text-ink-2">
-                        We sent a link to {form.email}. Open it to finish setting up your account —
-                        it expires in 24 hours. Nothing is created until you do.
-                    </p>
-                </div>
-            ) : (
-                <>
-                    <h1 className="text-3xl">Create an account</h1>
-                    <p className="mt-2 max-w-xl text-ink-2">
-                        For self-hosted licences. If you run on our cloud, sign in with the same
-                        details you use for your Vantage instance.
-                    </p>
-                    <form onSubmit={submit} className="mt-6 grid gap-4">
-                        <Field
-                            label="Organisation"
-                            required
-                            value={form.name}
-                            onChange={(e) => setForm({ ...form, name: e.target.value })}
-                        />
-                        <Field
-                            label="Email"
-                            type="email"
-                            required
-                            value={form.email}
-                            onChange={(e) => setForm({ ...form, email: e.target.value })}
-                        />
-                        <Field
-                            label="Password"
-                            type="password"
-                            required
-                            minLength={12}
-                            hint="At least 12 characters."
-                            value={form.password}
-                            onChange={(e) => setForm({ ...form, password: e.target.value })}
-                            error={error ?? undefined}
-                        />
-                        {/* Honeypot: off-screen, unlabelled for humans, irresistible to bots. */}
-                        <input
-                            type="text"
-                            name="website"
-                            tabIndex={-1}
-                            autoComplete="off"
-                            aria-hidden="true"
-                            value={form.website}
-                            onChange={(e) => setForm({ ...form, website: e.target.value })}
-                            className="absolute left-[-9999px] h-0 w-0"
-                        />
-                        <Button type="submit" disabled={state === "busy"}>
-                            {state === "busy" ? "Creating…" : "Create account"}
-                        </Button>
-                    </form>
-                </>
-            )}
-        </main>
-    );
-}

adminsite/lib/api.ts

@@ -296,8 +296,6 @@ export const api = {
     staffLogin: (email: string, password: string) =>
         post<Session>("/auth/staff/login", { email, password }),
     logout: () => post<{ ok: boolean }>("/auth/logout"),
-    signup: (payload: { name: string; email: string; password: string; website?: string }) =>
-        post<{ pending: boolean }>("/auth/signup", payload),
     verify: (token: string) =>
         req<{ verified: boolean; needs_password?: boolean }>(
             `/auth/verify?token=${encodeURIComponent(token)}`,

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

@@ -94,6 +94,11 @@ vantage/
 │   ├── app/(staff)/staff/           # operations, accounts, licences, plans, audit
 │   ├── components/                  # AppBar, PageHeader, PageFrame, InstanceRecord
 │   └── lib/                         # api client, session guards, formatters
+├── docsite/                         # user documentation (Docusaurus, static)
+│   ├── docs/                        # getting-started, vantage, hq, reference, operations
+│   ├── src/css/custom.css           # site/'s tokens, copied, mapped onto --ifm-*
+│   ├── sidebars.ts                  # authored by hand, not autogenerated
+│   └── nginx.conf                   # serves the build under /docs
 ├── shared/                          # imported by server, sitesvc and admin
 │   ├── mail/                        # the one email system: transport + tmpl templates
 │   ├── license/                     # payload, sign, verify, trusted keys, plans
@@ -115,9 +120,9 @@ Upload a public key, assign it per server, revoke softly. The agent diffs desire
 
 ### Workflows
 
-A library of reusable **steps** (bash or PowerShell scripts with declared inputs, outputs, and secret refs) composed into **workflows** targeting a set of servers. Running one snapshots the resolved steps into a `WorkflowRun`, then dispatches `RunStepCmd` over the agent command stream. Step stdout/stderr streams back as `StepOutputChunk` and is written to a log file on disk; the UI streams it live. Steps support `on_failure: stop|continue|retry`, per-run env passed between steps via `output_env`, and a per-run workspace directory the agent cleans up at the end.
+A library of reusable **steps** (bash or PowerShell scripts with declared inputs, outputs, and secret refs) composed into **workflows** targeting a set of servers. Running one snapshots the resolved steps into a `WorkflowRun`, then dispatches `RunStepCmd` over the agent command stream. Step stdout/stderr streams back as `StepOutputChunk` and is written to MongoDB (`workflow_log_lines`, one document per line); the UI streams it live. Steps support `on_failure: stop|continue|retry`, per-run env passed between steps via `output_env`, and a per-run workspace directory the agent cleans up at the end.
 
-Default steps are seeded per org at boot (`SeedDefaultSteps`). Logs are swept by retention (`workflow_log_retention_days`; nil = 30 days, 0 = forever).
+Default steps are seeded per org at boot (`SeedDefaultSteps`) from `VANTAGE_DEFAULT_STEPS_DIR`, which `server/Dockerfile` bakes to `/opt/default-steps` from the repo's `default_steps/`. Deliberately **not** under `/data` — that is a bind mount, so the library would be editable from the host. Adding a step there means committing a file and rebuilding, which is why `default_steps/` is in the `server` rebuild trigger. **Steps with `source: "default"` are read-only**: `UpdateStep`/`DeleteStep` refuse with `ErrDefaultStep` (409), because seeding rewrites them on every boot, so an edit would silently revert and a delete would come back. `web/` mirrors this — the step modal opens read-only, Delete is hidden, and the designer's per-step script override is `readOnly` for a default library step — but as elsewhere, the API is the boundary and the UI is the courtesy. Seeding writes straight to the collection rather than through `UpdateStep`, so the guard does not lock out the seeder. Logs are swept by retention (`workflow_log_retention_days`; nil = 30 days, 0 = forever).
 
 ### Monitors
 
@@ -133,7 +138,72 @@ 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.
+
+### Running more than one server replica
+
+An agent's `CommandStream` terminates on exactly **one** server process. Every
+piece of coordination below exists because of that single fact: with several
+replicas, the process asked to do something to an agent is almost never the
+process holding that agent's stream.
+
+`server/internal/bus` is the Redis message bus that closes the gap. It adds no
+infrastructure — Redis was already required for sessions — and it is **not
+optional on a single-replica deployment**: dispatch takes the bus path always,
+so the code running in production is the code running everywhere, rather than a
+rare cross-pod branch that only fails under load.
+
+| Concern                | How it crosses replicas                                                                                                                                                                       |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Which pod owns an agent | `vantage:agent:<server_id>` holds the owner's node ID with a 30s TTL, renewed every 10s. `Dispatcher.IsConnected` is an `EXISTS` on it                                                        |
+| Sending a command       | published to `vantage:cmd:<server_id>`; the owner pod acks on `vantage:ack:<command_id>`. **Request/ack, not a queue** — a command whose owner died must fail loudly (503) rather than queue |
+| Step results            | the owner pod publishes to `vantage:res:<command_id>`; the pod driving the run subscribes **before** dispatching, or a fast agent answers into a channel nobody has joined                    |
+| Step output             | never crosses. The dispatch envelope carries the secret mask list, so the owner pod masks and writes lines itself — unmasked bytes stay off the bus                                          |
+| Console relay           | the envelope asks the owner pod to bind the listener, and the ack returns **that pod's** address for guacd. The relay's failure reason comes back on `vantage:proxyend:<proxy_id>`           |
+| Background jobs         | `bus.RunAsLeader` — one Redis lock named `housekeeping`                                                                                                                                       |
+
+**Workflow logs are in MongoDB** (`workflow_log_lines`, one document per line,
+with a `workflow_log_seq` counter document per run/server). Two pods write the
+same log concurrently — the run's pod emits markers, the agent's pod emits
+output — so ordering only means anything if both draw sequence numbers from the
+same counter. `StepRun.log_offset` is that sequence number now, not a byte
+offset. Writes are batched (128 lines or 250ms) and capped: 8 KB per line,
+200k lines per server-run, after which one final `[vantage] log truncated`
+marker is written and the rest is dropped. Without that cap a `yes` in a step
+is a database incident. **Nothing writes to `/data` any more**, which is why
+`server.persistence` now defaults to off and `VANTAGE_WORKFLOW_LOG_DIR` is gone.
+
+**The leader lock is not an optimisation.** N replicas each running the monitor
+scheduler means each check fires N times, each incident notification reaches the
+customer N times, and each hourly rollup is written N times; N reapers race to
+purge the same Free instance. `monitorsched`, `StartReaper`, `StartLogSweeper`,
+`StartAuditSweeper` and the offline sweep therefore all run inside one
+`RunAsLeader("housekeeping", …)` — one role, one lock. Each takes a context
+cancelled the instant leadership is lost, and must return when it is.
+
+Redis rather than a Kubernetes `Lease` so Compose takes the identical path: one
+implementation to reason about, not two.
+
+Two deployment requirements come with `replicaCount > 1`: every replica must
+share **one** Redis (a per-pod Redis partitions the bus and every agent looks
+offline to two thirds of the fleet), and `POD_IP` must be set — the chart does
+it from the downward API — because `PROXY_ADVERTISE_HOST` names the Service, and
+a Service cannot address the one pod holding a console listener.
 
 ### Inventory and OS updates
 
@@ -147,19 +217,25 @@ Agents report CPU/memory/swap/partitions/kernel — metrics every 30s, full stat
 
 `site/` is a separate Next.js app built exactly like `web/` — `output: "standalone"`, run by Node in a `node:26-alpine` image, listening on `3000` and published as `3003`. The contact form posts to `sitesvc`; account signup posts to `admin` (`NEXT_PUBLIC_ADMIN_API_URL`), which creates an HQ account, not an org — the control plane is not touched until the customer later creates a cloud instance from the portal.
 
-`adminsite/` is built the same way and published as `3004`, served at **`vantage-hq.hostxtra.co.uk`** — deliberately *outside* `*.vantage.hostxtra.co.uk`, because that namespace is per-tenant instance subdomains and `APP_ROOT_LABEL` resolves an org from the label before `vantage`. It shares `site/`'s design tokens verbatim (see Frontend below) and, unlike `web/`, does **not** proxy through a Next rewrite: the browser calls `admin` directly, so `ADMIN_API_URL` must be browser-reachable. Authenticated requests work cross-origin only because both hosts share the registrable domain `hostxtra.co.uk`, which keeps `admin_session`'s `SameSite=Lax` cookie in play.
+`adminsite/` is built the same way and published as `3004`, served at **`vantage-hq.hostxtra.co.uk`** — deliberately _outside_ `*.vantage.hostxtra.co.uk`, because that namespace is per-tenant instance subdomains and `APP_ROOT_LABEL` resolves an org from the label before `vantage`. It shares `site/`'s design tokens verbatim (see Frontend below) and, unlike `web/`, does **not** proxy through a Next rewrite: the browser calls `admin` directly, so `ADMIN_API_URL` must be browser-reachable. Authenticated requests work cross-origin only because both hosts share the registrable domain `hostxtra.co.uk`, which keeps `admin_session`'s `SameSite=Lax` cookie in play.
 
 **`ADMIN_ORIGIN` must list every browser origin that calls admin — currently two**: `https://vantage-hq.hostxtra.co.uk` for the console, and `https://vantage.hostxtra.co.uk` because the marketing site's `/start` form posts account signups to admin directly. It is comma-separated. A missing origin does not produce a 403: `cors()` simply omits the `Access-Control-Allow-Origin` header and still answers the preflight `204`, so the browser blocks the request and **admin logs nothing at all**. Symptom is a CORS preflight failure on an endpoint that works fine under curl.
 
 `sitesvc/` (port `8082`) now owns only the contact flow:
 
-| Form    | Endpoint             | Effect                                                                  |
-| ------- | --------------------- | ----------------------------------------------------------------------- |
-| Contact | `POST /api/contact`   | Emails `support@hostxtra.co.uk`, `Reply-To` the sender. Nothing stored. |
+| Form    | Endpoint            | Effect                                                                  |
+| ------- | ------------------- | ----------------------------------------------------------------------- |
+| Contact | `POST /api/contact` | Emails `support@hostxtra.co.uk`, `Reply-To` the sender. Nothing stored. |
 
 Account signup lives in `admin` instead (`POST /auth/signup`, `GET /auth/verify?token=…`) — see Signup and verification below.
 
-`site`, `sitesvc` and `admin` are deliberately **excluded from the self-hosted deployment**: `deploy/docker-compose.yml` mentions none of them, and they live in `deploy/docker-compose.site.yml` instead.
+`site`, `sitesvc`, `admin` and `docsite` are deliberately **excluded from the self-hosted deployment**: `deploy/docker-compose.yml` mentions none of them, and they live in `deploy/docker-compose.site.yml` instead.
+
+### Documentation site
+
+`docsite/` is the user-facing documentation — Docusaurus 3 in docs-only mode (`routeBasePath: "/"`, no blog), one version tracking `main`, search indexed at build time by `@easyops-cn/docusaurus-search-local` so nothing external is keyed or called. It documents the **product**, not the codebase: this file remains the contributor's map, and the two are allowed to differ in altitude but not in fact. Five sections — Getting started, Vantage, Vantage HQ, Reference, Operations — with `sidebars.ts` authored by hand so ordering is a decision rather than a filename accident.
+
+Unlike the three Next apps it builds to static files, so its runtime stage is `nginx:alpine-slim` rather than Node, and it listens on `80`. See the compose note below for the `/docs` prefix, which is the one thing about it that is easy to get wrong.
 
 ```bash
 # self-hosted install — no marketing site, no sitesvc
@@ -234,7 +310,7 @@ instance authenticates it exactly as it authenticates anyone else, with **no
 runtime dependency on admin**. Revoking deletes that row — the control plane has
 no disabled state, and a row that exists is a row that can sign in.
 
-`instance_members` in admin's database is only admin's *index* of those
+`instance_members` in admin's database is only admin's _index_ of those
 projections; the control-plane row is the access. That is why a failed
 `instance_members` insert unwinds the projection, and why the boot backfill can
 rebuild the index from the control plane but never the other way round.
@@ -266,7 +342,7 @@ password-change endpoint at all, so there is no competing writer for the hash.
 - **Host/org guard** — `APP_ROOT_LABEL` (default `vantage`) defines the app root label. A request to `<slug>.vantage.<tld>` resolves that org from the slug and rejects sessions belonging to a different one. Org lookups are cached for 60s.
 
 Unique indexes are a **security property**, not an optimisation. `users` is
-unique on `(instance_id, email)` — one address is one user *within* an instance,
+unique on `(instance_id, email)` — one address is one user _within_ an instance,
 and the same address may hold a user in several instances, because an account's
 people are projected into each instance they are granted. This is sufficient only
 because **every lookup by email is scoped by instance**; there is deliberately no
@@ -304,6 +380,7 @@ Key-state polling stays on the 30s `SyncKeys` interval. Full message definitions
 Unauthenticated:
 
 ```
+GET  /healthz            /readyz             # liveness / readiness probes
 GET  /install            /install.ps1        # dynamic agent install scripts
 GET  /update             /update.ps1
 GET  /auth/bootstrap-status
@@ -406,11 +483,11 @@ GET  /health/injection · /health/billing
 
 Paddle is merchant of record; `admin/internal/paddle` is a thin REST client (no vendor SDK) and the only place that talks to it. **Free is entirely outside Paddle** — the shipped self-serve Free flow owns its own renewal, so no £0 subscription exists; an account learns its `paddle_customer_id` from its first paid webhook. Checkout happens in the browser (`@paddle/paddle-js`, token baked into the adminsite build); the server only updates a live subscription (`PUT /instances/:id/entitlement`) and mints a portal session.
 
-`POST /api/paddle/webhook` is the **only** issuing path for paid plans: signature-verified with `PADDLE_WEBHOOK_SECRET` (boot-required), idempotent via `paddle_events`, and a function of the subscription's *current* line items — resolved back to a plan and configuration by `catalogue.ResolveItems`, so out-of-order delivery is correct by construction. A confirmed webhook promotes the entitlement `desired`→`granted` and signs from `granted` **only**; a checkout is built from `desired`. `subscription.canceled` and `past_due` take **no licence action** — the licence runs to its (grace-padded) expiry, then the existing lifecycle sweep lapses the instance. A renewal (`transaction.completed`, origin `subscription_recurring`) is the only moment a scheduled reduction collapses `desired` into `granted`. Self-hosted purchase creates a placeholder instance before payment (`POST /instances/self-hosted`); the licence is issued only once the customer pastes the install's real UUID (`POST /instances/:id/claim-link`), because a licence binds to that UUID.
+`POST /api/paddle/webhook` is the **only** issuing path for paid plans: signature-verified with `PADDLE_WEBHOOK_SECRET` (boot-required), idempotent via `paddle_events`, and a function of the subscription's _current_ line items — resolved back to a plan and configuration by `catalogue.ResolveItems`, so out-of-order delivery is correct by construction. A confirmed webhook promotes the entitlement `desired`→`granted` and signs from `granted` **only**; a checkout is built from `desired`. `subscription.canceled` and `past_due` take **no licence action** — the licence runs to its (grace-padded) expiry, then the existing lifecycle sweep lapses the instance. A renewal (`transaction.completed`, origin `subscription_recurring`) is the only moment a scheduled reduction collapses `desired` into `granted`. Self-hosted purchase creates a placeholder instance before payment (`POST /instances/self-hosted`); the licence is issued only once the customer pastes the install's real UUID (`POST /instances/:id/claim-link`), because a licence binds to that UUID.
 
 ## MongoDB Collections
 
-`servers` · `keys` · `assignments` · `orgs` · `users` · `org_oidc` · `settings` · `secrets` · `workflows` · `workflow_steps` · `workflow_runs` · `monitors` · `incidents` · `monitor_rollups` · `notification_channels` · `console_sessions` · `audit_logs` · `migrations`
+`servers` · `keys` · `assignments` · `orgs` · `users` · `org_oidc` · `settings` · `secrets` · `workflows` · `workflow_steps` · `workflow_runs` · `workflow_log_lines` · `workflow_log_seq` · `monitors` · `incidents` · `monitor_rollups` · `notification_channels` · `console_sessions` · `audit_logs` · `migrations`
 
 Every document except `migrations` carries `org_id`. Struct definitions are the source of truth — see `server/internal/models/`.
 
@@ -422,9 +499,10 @@ Notes that are not obvious from the structs:
 - `assignments.revoked_at: null` means active. Revocation is soft, preserving audit history.
 - `workflow_runs.steps_snapshot` freezes the resolved steps so editing the library never rewrites history.
 - `console_sessions.token_consumed_at` is set atomically to enforce one-time use.
+- `workflow_log_lines` is keyed `(run_id, server_id, seq)` — the index is not an optimisation, every read is a range scan over it. `workflow_log_seq` holds one counter document per `run_id/server_id`, which is what lets two pods interleave into one ordered log. Neither carries `instance_id`: they are reached only through a run, and a run is already scoped.
 - `users.auth_source` is `local`, `oidc` or `hq`. An `hq` user was projected from a Vantage HQ account and carries `hq_user_id`; HQ owns its role, password and existence.
 
-Admin's own database is separate and holds `accounts` · `admin_instances` · `licenses` · `subscriptions` · `plans` · `catalogue` · `entitlements` · `paddle_events` · `staff_users` · `customer_users` · `instance_members` · `admin_audit`. `paddle_events` is the webhook idempotency log, unique on `event_id`: an event is claimed there before processing, and a duplicate of a handled event is a 200 no-op. `instance_members` is unique on `(instance_id, customer_user_id)` — one person holds at most one user in one instance, which makes a grant idempotent-by-refusal rather than silently doubling a projection. It is an *index* of the control-plane rows, not the authority (see "Grants project, they do not federate"). Admin has no migrations collection; `models.Backfill` runs on every boot and is idempotent by filtering on the absence of what it writes.
+Admin's own database is separate and holds `accounts` · `admin_instances` · `licenses` · `subscriptions` · `plans` · `catalogue` · `entitlements` · `paddle_events` · `staff_users` · `customer_users` · `instance_members` · `admin_audit`. `paddle_events` is the webhook idempotency log, unique on `event_id`: an event is claimed there before processing, and a duplicate of a handled event is a 200 no-op. `instance_members` is unique on `(instance_id, customer_user_id)` — one person holds at most one user in one instance, which makes a grant idempotent-by-refusal rather than silently doubling a projection. It is an _index_ of the control-plane rows, not the authority (see "Grants project, they do not federate"). Admin has no migrations collection; `models.Backfill` runs on every boot and is idempotent by filtering on the absence of what it writes.
 
 `plans` is keyed on `(deployment, tier)` — six rows, two deployments times three tiers — and holds base allowances only. **Every Paddle price ID lives in `catalogue`**, one row per priceable component (`base`, `limit`, `feature`), because a metered plan is priced by several prices and one map on a plan row cannot express that. `entitlements` holds one row per instance with `desired` beside `granted`: the checkout is built from `desired`, a licence is only ever signed from `granted`, and an abandoned checkout therefore leaves a `desired` that reached nothing. The two Free plans have **no catalogue rows at all**, which is what keeps Free outside Paddle.
 
@@ -498,34 +576,63 @@ Windows: MSI built by CI (WiX), or `installer/setup.ps1` registering the agent a
 
 ## Environment Variables (server)
 
-| Name                       | Required        | Notes                                                                                                                                                      |
-| -------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GRPC_HOST`                | **yes**         | `host:port` agents dial. Boot fails without it — there is no safe default; falling back to the web host would hand agents a port that does not speak gRPC. |
-| `MONGO_URI`                | no              | default `mongodb://localhost:27017`                                                                                                                        |
-| `MONGO_DB`                 | no              | default `vantage`                                                                                                                                          |
-| `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.                                                 |
-| `GITEA_HOST`               | yes             | used to build install scripts and agent download URLs                                                                                                      |
-| `GUACD_ADDR`               | no              | default `guacd:4822`                                                                                                                                       |
-| `APP_ROOT_LABEL`           | no              | default `vantage`; wrong value disables the host/session org guard                                                                                         |
-| `VANTAGE_WORKFLOW_LOG_DIR` | no              | where run logs are written                                                                                                                                 |
+| Name                       | Required        | Notes                                                                                                                                                                                                                                                                                                              |
+| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GRPC_HOST`                | **yes**         | `host:port` agents dial. Boot fails without it — there is no safe default; falling back to the web host would hand agents a port that does not speak gRPC.                                                                                                                                                         |
+| `MONGO_URI`                | no              | default `mongodb://localhost:27017`                                                                                                                                                                                                                                                                                |
+| `MONGO_DB`                 | no              | default `vantage`                                                                                                                                                                                                                                                                                                  |
+| `REDIS_USERNAME`           | no              | Redis 6+ ACL user. Leave empty for a legacy `requirepass` instance — go-redis then sends AUTH with one argument instead of two                                                                                                                                                                                     |
+| `REDIS_PASSWORD`           | no              | empty for an unauthenticated Redis                                                                                                                                                                                                                                                                                 |
+| `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                                                                                                                                                                                                                                                 |
+| `POD_IP`                   | no              | this pod's own address, set by the Helm chart from the downward API. **Takes precedence over `PROXY_ADVERTISE_HOST`** — a console relay listener belongs to one replica, and a Service address names all of them                                                                                                     |
+| `VANTAGE_MIGRATE_ONLY`     | no              | run schema setup (migrations, index builders, default-step seeding) and exit without serving. `GRPC_HOST` is not required in this mode. Set by the Helm chart's pre-upgrade Job                                                                                                                                                          |
+| `VANTAGE_SKIP_MIGRATIONS`  | no              | serve without running schema setup, on the assumption a Job already did. Set by the chart's Deployment whenever `server.migrationJob.enabled`. Unset under Compose, where one process still migrates and then serves                                                                                                                    |
 | `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 |
 
 **sitesvc** (`deploy/docker-compose.site.yml` only):
 
-| Name                              | Required        | Notes                                                                                                                                                                                                                                                                                                                                            |
-| --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Name                              | Required        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `MONGO_URI`                       | yes             | **must point at the control plane's database.** sitesvc no longer provisions orgs itself, but it still refuses to start (`RequireMigratedDatabase`) against a database that has not run migration `0004` (the `orgs` → `instances` rename), and it (re)declares the shared `users.email` / `instances.slug` indexes at boot. The database name is read from the URI path; a URI without one is refused rather than defaulted. Note this differs from the server, which takes `MONGO_DB` separately. |
-| `SMTP_HOST` / `SMTP_FROM`         | yes             | without them the contact form refuses (503) rather than silently dropping                                                                                                                                                                                                                                                                        |
-| `SMTP_TO`                         | no              | default `support@hostxtra.co.uk`; contact enquiries only                                                                                                                                                                                                                                                                                         |
-| `SMTP_PORT`                       | no              | default `587`; `465` uses implicit TLS                                                                                                                                                                                                                                                                                                           |
-| `SMTP_USERNAME` / `SMTP_PASSWORD` | no              | auth skipped when username is empty                                                                                                                                                                                                                                                                                                              |
-| `SITE_ORIGIN`                     | yes in practice | comma-separated allowed origins; unset refuses every cross-origin browser request                                                                                                                                                                                                                                                                |
-| `TRUST_PROXY`                     | no              | only `true` behind a proxy that overwrites `X-Forwarded-For`, or clients spoof past the rate limiter                                                                                                                                                                                                                                             |
+| `SMTP_HOST` / `SMTP_FROM`         | yes             | without them the contact form refuses (503) rather than silently dropping                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `SMTP_TO`                         | no              | default `support@hostxtra.co.uk`; contact enquiries only                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `SMTP_PORT`                       | no              | default `587`; `465` uses implicit TLS                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `SMTP_USERNAME` / `SMTP_PASSWORD` | no              | auth skipped when username is empty                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `SITE_ORIGIN`                     | yes in practice | comma-separated allowed origins; unset refuses every cross-origin browser request                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `TRUST_PROXY`                     | no              | only `true` behind a proxy that overwrites `X-Forwarded-For`, or clients spoof past the rate limiter                                                                                                                                                                                                                                                                                                                                                                                                |
 
-`deploy/docker-compose.yml` runs four services: `redis`, `guacd`, `server` (8080 + 9090), `web` (3000). MongoDB is external. `deploy/docker-compose.site.yml` adds four more — `site` (3003), `sitesvc` (8082), `admin` (8083) and `adminsite` (3004) — and is only used on vantage.hostxtra.co.uk.
+### Ingress (Helm, Traefik)
 
-`LICENSE_SIGNING_KEY` appears in **exactly one service in exactly one compose file**: `admin` in `docker-compose.site.yml`. It must never be added to `server`, and the self-hosted `docker-compose.yml` must never mention `admin` or `adminsite` at all. Admin uses an external Redis via `REDIS_ADDR`/`REDIS_USERNAME`/`REDIS_PASSWORD`; the base compose hardcodes `redis:6379` for `server`, so those variables reach admin only.
+`ingress.enabled` publishes **two** hostnames, because the two audiences arrive over different protocols:
+
+| Values                                       | Route                                                                                       |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `ingress.web.host` (+ `web.extraHosts`)      | browsers → `web:3000`                                                                        |
+| `ingress.api.paths` (when `api.enabled`)     | `/api`, `/auth` → `<release>-server:8080`, bypassing the Next proxy                          |
+| `ingress.grpc.host`                          | agents → a dedicated `<release>-server-grpc` Service on 9090, annotated `serversscheme: h2c` |
+
+**`ingress.web.host` is normally a wildcard.** `*.vantage.example.com` is the per-tenant instance namespace — `APP_ROOT_LABEL` resolves the instance from the label. A Kubernetes wildcard host matches **exactly one** label, so it does not match the apex, and here that is correct rather than a gap: `vantage.hostxtra.co.uk` is the marketing site (`site/`, in `docker-compose.site.yml`), which this chart does not deploy. `extraHosts` is for a genuine second name; adding the apex to it would put the control plane on the marketing host. Every host in the list gets identical paths.
+
+**`ingress.api.enabled` routes `/api` and `/auth` straight to the server.** Both arrangements work — without it `web` proxies those prefixes onward itself (`web/next.config.ts`) — but edge routing is one hop shorter and matches what the Nginx Proxy Manager in front of the Docker deployment already does, so leaving it off makes the request path a different shape on Kubernetes than in production. It stays **off by default** because it only helps where the server is reachable on the same host and certificate as `web`; turning it on blindly moves the whole API onto a route that may not be provisioned. Traefik derives router priority from rule length, so `PathPrefix(/api)` outranks the catch-all `/` with no priority annotation needed.
+
+**The gRPC route needs its own Service.** The server terminates no TLS; it speaks plain h2c and always has, with TLS terminated by whatever sits in front. Traefik will not use h2c to a backend unless the *Service* says so, and that annotation applies to every port on the Service — so annotating the shared two-port `<release>-server` would force h2c on its HTTP port too.
+
+**`server.env.grpcHost` is not derived from `ingress.grpc.host`, and the chart refuses to render if they disagree.** Agents dial whatever `grpcHost` says, and it is baked into every install one-liner; left pointing at the in-cluster Service while agents arrive through the ingress, every install succeeds and every agent then fails to connect, with nothing in the control plane explaining why. Guessing at the port (443? 9090?) would be worse than stopping.
+
+TLS is `ingress.tls.secretName` / `grpcSecretName` (pre-existing certificates) **or** `certResolver` (Traefik ACME). Setting neither while `tls.enabled` produces a TLS router with no certificate, so Traefik serves its self-signed default — which looks valid and is trusted by nothing. NOTES.txt warns on install rather than the chart failing, since it is a real if unusual choice behind another terminator.
+
+---
+
+`deploy/docker-compose.yml` runs four services: `redis`, `guacd`, `server` (8080 + 9090), `web` (3000). MongoDB is external. `deploy/docker-compose.site.yml` adds five more — `site` (3003), `sitesvc` (8082), `admin` (8083), `adminsite` (3004) and `docsite` (3005) — and is only used on vantage.hostxtra.co.uk.
+
+`docsite` is the odd one: a **static** build served by `nginx:alpine-slim`, not a Node runtime, and it listens on `80` rather than `3000`. It is reached at **`vantage.hostxtra.co.uk/docs`** — a path on the marketing host, routed by its own Nginx Proxy Manager location, which must sort **above** the catch-all forwarding to `site:3003` or Next answers the 404. A path and not a subdomain because `*.vantage.hostxtra.co.uk` is the per-tenant instance namespace and `APP_ROOT_LABEL` would read a `docs.` label as a tenant slug. NPM forwards the **full** path upstream — it does not strip `/docs` — so `DOCS_BASE_URL`, the proxy location and the directory the image copies the build into (`/usr/share/nginx/html/docs`) must all agree. When they do not, the HTML loads and every asset 404s.
+
+`LICENSE_SIGNING_KEY` appears in **exactly one service in exactly one compose file**: `admin` in `docker-compose.site.yml`. It must never be added to `server`, and the self-hosted `docker-compose.yml` must never mention `admin` or `adminsite` at all. Admin uses an external Redis via `REDIS_ADDR`/`REDIS_USERNAME`/`REDIS_PASSWORD`. `server` now reads the same three, so a Kubernetes install can point at a managed Redis; the base compose still hardcodes an unauthenticated `redis:6379` for it, so in Docker those credentials remain admin's alone.
 
 ---
 
@@ -547,17 +654,20 @@ Windows: MSI built by CI (WiX), or `installer/setup.ps1` registering the agent a
 
 Next.js 16 (App Router) + React 18, Tailwind 3, TanStack Query. Guacamole client bundled locally in `web/lib/guacamole-common.js`.
 
-All three apps are **one visual system**, anchored on the logo navy. What differs between them is which end of it they stand on:
+All four apps are **one visual system**, anchored on the logo navy. What differs between them is which end of it they stand on:
 
-| App | Ground | Accent | Themes |
-| --- | --- | --- | --- |
-| `web/` | `--ground` dark, `#071628` | `#5b9be8` | dark only, locked |
-| `site/` | token-based | `#0b2a58` light / `#5b9be8` dark | light + dark |
-| `adminsite/` | token-based | `#0b2a58` light / `#5b9be8` dark | light + dark, light default |
+| App          | Ground                     | Accent                           | Themes                      |
+| ------------ | -------------------------- | -------------------------------- | --------------------------- |
+| `web/`       | `--ground` dark, `#071628` | `#5b9be8`                        | dark only, locked           |
+| `site/`      | token-based                | `#0b2a58` light / `#5b9be8` dark | light + dark                |
+| `adminsite/` | token-based                | `#0b2a58` light / `#5b9be8` dark | light + dark, light default |
+| `docsite/`   | token-based                | `#0b2a58` light / `#5b9be8` dark | light + dark, light default |
 
-`adminsite/app/globals.css` holds `site/app/globals.css`'s token blocks **copied verbatim** — same names, same values. `web/app/globals.css` holds the same tokens too, but only the **dark** values, since it does not switch. **Change a token in all three files in the same commit; nothing enforces the match automatically**, the same shape of hazard as sitesvc's mirrored slug rules.
+`adminsite/app/globals.css` and `docsite/src/css/custom.css` hold `site/app/globals.css`'s token blocks **copied verbatim** — same names, same values. `web/app/globals.css` holds the same tokens too, but only the **dark** values, since it does not switch. **Change a token in all four files in the same commit; nothing enforces the match automatically**, the same shape of hazard as sitesvc's mirrored slug rules.
 
-There is a **fourth** copy, and it is the one people forget: `shared/mail/templates/layout.html.tmpl` carries web/'s dark values as literal hex. Email clients support neither `var()` nor a reliable `prefers-color-scheme`, so the token indirection is simply not available there — an email is read before the recipient clicks through to the control plane, and the two should not look like different products. Every colour in the email system is in that one file, in the same way no component in the three web apps carries a hex.
+`docsite/` is the one place the tokens are not consumed through Tailwind: everything below its token block maps Docusaurus's `--ifm-*` variables onto them. Docusaurus already stamps `data-theme` on `<html>`, which is the selector `site/`'s dark block keys on, so the built-in toggle needed no wiring. The rule holds all the same — no rule in that file outside the token blocks carries a hex. The one concession is `docsite/static/img/favicon.svg`, which must, for the same reason the email layout must: a browser tab cannot read a token.
+
+There is a **fifth** copy, and it is the one people forget: `shared/mail/templates/layout.html.tmpl` carries web/'s dark values as literal hex. Email clients support neither `var()` nor a reliable `prefers-color-scheme`, so the token indirection is simply not available there — an email is read before the recipient clicks through to the control plane, and the two should not look like different products. Every colour in the email system is in that one file, in the same way no component in the four web apps carries a hex.
 
 Tailwind in all three maps `var(--…)` references only, so **no component in any of them may carry a hex value**. The names differ per app on purpose, because each app has its own subject: `site/` calls the semantic three `--up`/`--pend`/`--down` for monitor state, `adminsite/` aliases them to `valid`/`warn`/`expired` for licence state, and `web/` to `success`/`warning`/`danger`. Same colours, honest names on each side.
 
@@ -614,7 +724,7 @@ GOOS=linux GOARCH=amd64 go build \
 
 ### `server-deploy.yml` — triggered on every push to `main`
 
-Builds and pushes six images to the Gitea container registry: `server`, `web`, `site`, `sitesvc`, `admin` and `adminsite`.
+Builds and pushes seven images to the Gitea container registry: `server`, `web`, `site`, `sitesvc`, `admin`, `adminsite` and `docsite`.
 
 Note that despite the name, **this workflow does not deploy** — it only builds and pushes. There is no SSH step. Rolling images out is a separate manual step on the host:
 
@@ -625,43 +735,60 @@ cd /opt/vantage && docker compose -f docker-compose.yml -f docker-compose.site.y
 
 **Each image only rebuilds when its own inputs changed.** A `git diff` against `github.event.before` decides, which is why the checkout uses `fetch-depth: 0` — the default shallow clone has one commit and nothing to diff — and why `git` is installed in the `docker:dind` container. The mapping follows the build contexts exactly:
 
-| Image | Rebuilds when |
-| --- | --- |
-| `server` | `server/`, `shared/`, `proto/`, `go.work` |
-| `admin` | `admin/`, `shared/`, `go.work` |
-| `sitesvc` | `sitesvc/`, `shared/`, `go.work` |
-| `web` · `site` · `adminsite` | their own directory only |
+| Image                        | Rebuilds when                             |
+| ---------------------------- | ----------------------------------------- |
+| `server`                     | `server/`, `shared/`, `proto/`, `go.work` |
+| `admin`                      | `admin/`, `shared/`, `go.work`            |
+| `sitesvc`                    | `sitesvc/`, `shared/`, `go.work`          |
+| `web` · `site` · `adminsite` · `docsite` | their own directory only      |
 
 `shared/` fans out to all three Go images because each of their Dockerfiles copies `shared/` from a root context — **if a fourth service ever imports `shared/`, add it to that list or it will ship stale**. A change to the workflow file rebuilds everything, since a build arg is baked into the image. So does anything that leaves no trustworthy base commit: a manual `workflow_dispatch`, a new branch, or a force-push whose old head is gone.
 
-The gap this leaves: **changing a repo variable pushes no commit, so nothing rebuilds.** After editing `API_URL`, `ADMIN_API_URL`, `HQ_URL` or `ADMIN_ENV`, run the workflow manually — that is what `workflow_dispatch` is there for. Base images also stop being refreshed on a service nobody touches; a periodic manual run covers that.
+The gap this leaves: **changing a repo variable pushes no commit, so nothing rebuilds.** After editing `ADMIN_API_URL`, `HQ_URL` or `ADMIN_ENV`, run the workflow manually — that is what `workflow_dispatch` is there for. Base images also stop being refreshed on a service nobody touches; a periodic manual run covers that.
+
+### `chart-release.yml` — validates on every chart change, publishes on `chart/v*` tags
+
+Two jobs' worth of work in one, split by trigger. Any push or PR touching `deploy/chart/` lints the chart and renders it four ways: defaults, a multi-replica install, external Redis and MongoDB, and a set of values that **must be refused**. That last one is the point — every safety rail in this chart is a template `fail`, and `helm lint` happily accepts a chart whose templates never execute, so only rendering proves they still fire.
+
+Publishing runs only on a `chart/v*` tag, to the Gitea Helm registry at `/api/packages/<owner>/helm/api/charts`. **`Chart.yaml` is the source of truth for the version**; the tag only selects which one to publish, and a tag that disagrees with `Chart.yaml` fails rather than stamping over it — the alternative leaves the repository disagreeing with what shipped. A version already in the registry is rejected by Gitea, which is intended: published chart versions are immutable.
+
+The registry host comes from `github.server_url`, so it cannot drift from the instance the workflow is running on. It authenticates with `REGISTRY_USER` + **`RELEASE_TOKEN`** — the pair `server-deploy.yml` actually uses for `docker login`. `REGISTRY_PASSWORD` is listed in the secrets table below but set by no workflow; passing an unset secret yields an empty password and Gitea answers `401 Failed to authenticate user`, which reads like a scope problem on a token that was never sent. The publish step therefore checks both are non-empty before it calls curl. `RELEASE_TOKEN` needs `write:package` in addition to `write:release`.
+
+```bash
+helm repo add vantage https://gitea.hostxtra.co.uk/api/packages/mrhid6/helm
+helm install vantage vantage/vantage --version 0.1.0
+```
 
 ### Tagging
 
 ```bash
 git tag agent/v1.0.0 && git push origin agent/v1.0.0   # agent release
+git tag chart/v0.1.0 && git push origin chart/v0.1.0   # helm chart package
 git push origin main                                    # server + web deploy
 ```
 
 ### Secrets / variables
 
-| Name                 | Type     | Value                                                                                                                                                                               |
-| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `RELEASE_TOKEN`      | Secret   | Gitea API token, `write:release`                                                                                                                                                    |
-| `REGISTRY_USER`      | Secret   | Gitea username                                                                                                                                                                      |
-| `REGISTRY_PASSWORD`  | Secret   | Gitea token, `write:packages`                                                                                                                                                       |
-| `GITEA_HOST`         | Variable | `gitea.hostxtra.co.uk`                                                                                                                                                              |
-| `DOCKER_HOST`        | Variable | registry host used for image tags                                                                                                                                                   |
-| `API_URL`            | Variable | baked into the `web` image at build time                                                                                                                                            |
-| `SITE_API_URL`       | Variable | **browser-reachable** sitesvc URL, baked into the `site` image. Required — if empty, both forms report "not connected" and submit nowhere. Must also be in sitesvc's `SITE_ORIGIN`. |
-| `SITE_CONTACT_EMAIL` | Variable | optional; address shown when a form is misconfigured                                                                                                                                |
-| `ADMIN_API_URL`      | Variable | **browser-reachable** admin URL, baked into **both** the `adminsite` and `site` images — `site/start` posts account signups straight to admin. Same footgun as `SITE_API_URL`: wrong here and every request fails at runtime with the not-connected panel. |
-| `ADMIN_ENV`          | Variable | `production` or `sandbox`; drives the persistent environment badge. Anything but `sandbox` reads as production.                                                                     |
-| `HQ_URL`             | Variable | optional; browser URL of the HQ portal, baked into `web` so an `hq`-sourced member links to where they are managed. Empty on self-hosted, which renders a plain label instead.       |
-| `PADDLE_CLIENT_TOKEN`| Variable | **browser** Paddle token, baked into the `adminsite` image for checkout. A repo-variable change pushes no commit, so rebuild `adminsite` manually via `workflow_dispatch` after editing it. |
-| `PADDLE_ENV`         | Variable | `sandbox` or `production`; baked into `adminsite` AND read by `admin` at runtime. Selects which `catalogue` price IDs are served, and must match on both sides.                       |
-| `PADDLE_API_KEY`     | Secret   | server-side Paddle key, read by `admin` at runtime. Boot-required.                                                                                                                    |
-| `PADDLE_WEBHOOK_SECRET` | Secret | webhook signature verification, read by `admin`. Boot-required — an unverified endpoint is one anyone can issue licences through.                                                     |
+| Name                    | Type     | Value                                                                                                                                                                                                                                                      |
+| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RELEASE_TOKEN`         | Secret   | Gitea API token. Needs `write:release` (agent releases), `write:package` (container images and the Helm chart). **This is the only token any workflow authenticates with** — `docker login` and the chart publish both pair it with `REGISTRY_USER`         |
+| `REGISTRY_USER`         | Secret   | Gitea username. Must own `RELEASE_TOKEN`, or basic auth is rejected                                                                                                                                                                                        |
+| ~~`REGISTRY_PASSWORD`~~ | —        | **Not used.** Named here historically; no workflow reads it. Referencing an unset secret yields an empty password and a `401 Failed to authenticate user` that looks like a token scope problem. Use `RELEASE_TOKEN`                                        |
+| `DOCKER_HOST`           | Variable | registry host used for image tags                                                                                                                                                                                                                          |
+| `API_URL`               | **not** a CI variable | `web` reads it at **runtime**, from the container environment — `next.config.ts` is evaluated when `server.js` boots in standalone mode, and the rewrites it feeds are server-side, never browser-side. Default `http://localhost:8080`; compose sets `http://server:8080`. `NEXT_PUBLIC_API_URL` is still honoured as a fallback for existing deployments. |
+| `SITE_API_URL`          | Variable | **browser-reachable** sitesvc URL, baked into the `site` image. Required — if empty, both forms report "not connected" and submit nowhere. Must also be in sitesvc's `SITE_ORIGIN`.                                                                        |
+| `SITE_CONTACT_EMAIL`    | Variable | optional; address shown when a form is misconfigured                                                                                                                                                                                                       |
+| `SITE_URL`              | Variable | browser URL of the marketing site, baked into `adminsite` so `/login` can point at `/start`. **Signup has no page in `adminsite` at all** — one signup form, on `site/`. Empty renders no link rather than one that 404s.                                  |
+| `ADMIN_API_URL`         | Variable | **browser-reachable** admin URL, baked into **both** the `adminsite` and `site` images — `site/start` posts account signups straight to admin. Same footgun as `SITE_API_URL`: wrong here and every request fails at runtime with the not-connected panel. |
+| `ADMIN_ENV`             | Variable | `production` or `sandbox`; drives the persistent environment badge. Anything but `sandbox` reads as production.                                                                                                                                            |
+| `HQ_URL`                | Variable | optional; browser URL of the HQ portal, baked into `web` so an `hq`-sourced member links to where they are managed. Empty on self-hosted, which renders a plain label instead.                                                                             |
+| `PADDLE_CLIENT_TOKEN`   | Variable | **browser** Paddle token, baked into the `adminsite` image for checkout. A repo-variable change pushes no commit, so rebuild `adminsite` manually via `workflow_dispatch` after editing it.                                                                |
+| `PADDLE_ENV`            | Variable | `sandbox` or `production`; baked into `adminsite` AND read by `admin` at runtime. Selects which `catalogue` price IDs are served, and must match on both sides.                                                                                            |
+| `PADDLE_API_KEY`        | Secret   | server-side Paddle key, read by `admin` at runtime. Boot-required.                                                                                                                                                                                         |
+| `PADDLE_WEBHOOK_SECRET` | Secret   | webhook signature verification, read by `admin`. Boot-required — an unverified endpoint is one anyone can issue licences through.                                                                                                                          |
+| `DOCS_URL`              | Variable | site `url` baked into `docsite`; `https://vantage.hostxtra.co.uk`. Empty falls back to that default rather than breaking the build.                                                                                                                        |
+| `DOCS_BASE_URL`         | Variable | `/docs/`. Must match the NPM location and the directory the image serves from — all three, or the HTML loads and every asset 404s.                                                                                                                         |
+| `APP_URL`               | Variable | control-plane link in `docsite`'s navbar.                                                                                                                                                                                                                  |
 
 ---
 
@@ -680,4 +807,15 @@ git push origin main                                    # server + web deploy
 - **`org_id` on every document** — isolation enforced at the query layer, not by separate databases.
 - **root only** — manages `/root/.ssh/authorized_keys`; no per-user key management.
 - **Windows agents are second-class by design** — register, heartbeat, run steps, report inventory; no `authorized_keys` management.
+- **Both `server` and `web` scale horizontally** — see "Running more than one server replica" below. `web` holds nothing; `server` holds per-agent state that is routed between replicas over Redis rather than duplicated.
 - **Deletion lives in the control plane** — admin sends the warnings because it knows the billing address; the control plane performs the delete because it is the only service that knows which collections carry `instance_id`. Mirroring that list into admin would drift, and a drift there deletes the wrong rows.
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

default_steps/step.bash.get_hostname.json

@@ -0,0 +1,12 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Get Host Name",
+  "description": "",
+  "interpreter": "bash",
+  "script": "HOSTNAME=$(hostname)\necho $HOSTNAME\necho \"HOSTNAME=$HOSTNAME\" \u003e\u003e $WORKFLOW_ENV",
+  "declared_outputs": [
+    "HOSTNAME"
+  ],
+  "declared_inputs": [],
+  "secret_refs": []
+}

default_steps/step.bash.list_directory.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "List Directory",
+  "description": "",
+  "interpreter": "bash",
+  "script": "if [ ! -e $path ]; then\n    echo \"file or directory doesn't exist: $path\"\n    exit 1\nfi\nls -l $path",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "path",
+      "default": "./",
+      "description": ""
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.start_linx_service.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Start Linux Service",
+  "description": "",
+  "interpreter": "bash",
+  "script": "echo \"starting service $serviceName\"\nsystemctl start $serviceName\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"failed to start service\"\n    exit 1\nfi",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": ""
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.stop_linux_service.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Stop Linux Service",
+  "description": "",
+  "interpreter": "bash",
+  "script": "echo \"stopping service $serviceName\"\nsystemctl stop $serviceName\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"failed to stop service\"\n    exit 1\nfi",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": ""
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.wget.json

@@ -0,0 +1,18 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "WGET",
+  "description": "",
+  "interpreter": "bash",
+  "script": "out=$(mktemp -p ./)\necho \"Downloading file from $url\"\nwget -q $url -O $out\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"failed to download file from url\"\n    exit 1\nfi\necho \"FILE_PATH=$out\" \u003e\u003e $WORKFLOW_ENV",
+  "declared_outputs": [
+    "FILE_PATH"
+  ],
+  "declared_inputs": [
+    {
+      "name": "url",
+      "default": "",
+      "description": ""
+    }
+  ],
+  "secret_refs": []
+}

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: 1.0.6
+appVersion: "1.0.6"

deploy/chart/vantage/templates/NOTES.txt

@@ -0,0 +1,72 @@
+Vantage has been deployed as release "{{ .Release.Name }}" in namespace "{{ .Release.Namespace }}".
+
+Services created:
+{{- if .Values.redis.enabled }}
+  - {{ .Release.Name }}-redis   (ClusterIP {{ .Values.redis.port }})
+{{- else }}
+  - Redis: not deployed, using external {{ .Values.redis.addr }}
+{{- end }}
+{{- if .Values.mongo.enabled }}
+  - {{ .Release.Name }}-mongo   (ClusterIP {{ .Values.mongo.port }})
+{{- else }}
+  - MongoDB: not deployed, using the external server.env.mongoUri
+{{- end }}
+  - {{ .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 }})
+
+Scaling (server.replicaCount / web.replicaCount):
+  - Both scale. Pin the image tags first — replicas on different builds serve
+    mismatched web asset hashes, and mixed server versions share one bus.
+  - server replicas route agent commands, step results and console relays to
+    each other over Redis, so every replica must use the SAME Redis. Workflow
+    logs are in MongoDB, not on a volume.
+  - Background work (monitor scheduler, Free reaper, log and audit retention,
+    the offline sweep) runs on one replica at a time under a Redis leader lock.
+  - server.persistence must be off to scale past one replica on a ReadWriteOnce
+    volume. Nothing writes to it any more.
+{{- if gt (int .Values.server.replicaCount) 1 }}
+  - Console relays are reached by pod IP; guacd must be able to dial pod IPs
+    directly (it can, inside the cluster network).
+{{- end }}
+{{- if .Values.server.migrationJob.enabled }}
+  - Migrations run in the {{ .Release.Name }}-migrate Job before each upgrade;
+    the pods skip them. Its logs are kept: kubectl logs job/{{ .Release.Name }}-migrate
+{{- end }}
+
+{{- if .Values.ingress.enabled }}
+
+Ingress (Traefik):
+  - Browsers:    https://{{ .Values.ingress.web.host }}
+{{- range .Values.ingress.web.extraHosts }}
+                 https://{{ . }}
+{{- end }}
+{{- if .Values.ingress.api.enabled }}
+    {{ join ", " .Values.ingress.api.paths }} go straight to the server; everything else to web.
+{{- else }}
+    Everything goes to web, which proxies /api and /auth onward. Set
+    ingress.api.enabled=true to route them at the edge instead.
+{{- end }}
+{{- if .Values.ingress.grpc.enabled }}
+  - Agents:      {{ .Values.ingress.grpc.host }} (gRPC, h2c behind TLS)
+    Agents dial server.env.grpcHost, currently {{ tpl .Values.server.env.grpcHost . }}.
+    Point DNS for both hostnames at the Traefik load balancer.
+{{- if not .Values.ingress.tls.enabled }}
+  - WARNING: ingress.tls.enabled is false. Agent tokens and session cookies
+    would cross the network in clear.
+{{- else if and (not .Values.ingress.tls.certResolver) (not .Values.ingress.tls.secretName) }}
+  - WARNING: TLS is on but neither ingress.tls.secretName nor
+    ingress.tls.certResolver is set, so Traefik will serve its self-signed
+    default certificate, which no agent and no browser will trust.
+{{- end }}
+{{- end }}
+{{- end }}
+
+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,85 @@
+{{/*
+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 -}}
+
+{{/*
+vantage.server.env renders the server container's environment.
+
+It lives here because two workloads need it identically: the Deployment and the
+pre-upgrade migration Job. A Job that connected to a different database than the
+pods it migrates for would be worse than no Job at all, so there is one copy and
+both read it.
+*/}}
+{{- define "vantage.server.env" -}}
+- name: MONGO_URI
+  {{- $mongoUri := tpl .Values.server.env.mongoUri . }}
+  {{- if and (not .Values.mongo.enabled) (contains (printf "%s-mongo" .Release.Name) $mongoUri) }}
+  {{- fail "mongo.enabled is false, so server.env.mongoUri must point at an external MongoDB rather than the in-chart one" }}
+  {{- end }}
+  value: {{ $mongoUri | quote }}
+- name: REDIS_ADDR
+  {{- if .Values.redis.enabled }}
+  value: "{{ .Release.Name }}-redis:{{ .Values.redis.port }}"
+  {{- else }}
+  {{- if not .Values.redis.addr }}
+  {{- fail "redis.enabled is false, so redis.addr must be set to an external Redis host:port" }}
+  {{- end }}
+  value: {{ .Values.redis.addr | quote }}
+  {{- end }}
+{{- if .Values.redis.auth.existingSecret }}
+- name: REDIS_USERNAME
+  valueFrom:
+    secretKeyRef:
+      name: {{ .Values.redis.auth.existingSecret }}
+      key: {{ .Values.redis.auth.usernameKey }}
+      optional: true
+- name: REDIS_PASSWORD
+  valueFrom:
+    secretKeyRef:
+      name: {{ .Values.redis.auth.existingSecret }}
+      key: {{ .Values.redis.auth.passwordKey }}
+{{- else }}
+{{- if .Values.redis.auth.username }}
+- name: REDIS_USERNAME
+  value: {{ .Values.redis.auth.username | quote }}
+{{- end }}
+{{- if .Values.redis.auth.password }}
+- name: REDIS_PASSWORD
+  value: {{ .Values.redis.auth.password | quote }}
+{{- end }}
+{{- end }}
+- 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: 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 }}
+{{- if eq .Values.server.env.deploymentType "cloud" }}
+- name: VANTAGE_DEPLOYMENT
+  value: "cloud"
+- name: FREE_INSTANCE_REAP_AFTER
+  value: {{ .Values.server.env.freeInstanceReapAfter | quote }}
+{{- end }}
+- name: POD_IP
+  valueFrom:
+    fieldRef:
+      fieldPath: status.podIP
+{{- end -}}

deploy/chart/vantage/templates/guacd.yaml

@@ -0,0 +1,47 @@
+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 }}
+  {{- if eq .Values.guacd.service.type "ClusterIP" }}
+  clusterIP: None
+  {{- end }}
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: guacd
+  ports:
+    - port: {{ .Values.guacd.service.port }}
+      targetPort: 4822

deploy/chart/vantage/templates/ingress.yaml

@@ -0,0 +1,173 @@
+{{- if .Values.ingress.enabled }}
+{{/*
+Two hostnames, because the two audiences arrive over different protocols.
+
+Browsers reach the web host. What answers there depends on the path: with
+ingress.api.enabled, /api and /auth go straight to the server and everything
+else goes to `web`. Without it, everything goes to `web`, which proxies those
+prefixes onward itself (web/next.config.ts).
+
+Both work. Routing at the edge is one hop shorter and is what the Nginx Proxy
+Manager deployment in front of the Docker install already does, so leaving it
+off changes the shape of the request path between the two deployments. It is
+still off by default, because turning it on where `web` is the only thing with
+a public certificate would strand /api behind a route nobody can reach.
+
+The web host is normally a wildcard — `*.vantage.example.com` — because that is
+the per-tenant instance namespace; APP_ROOT_LABEL resolves the instance from the
+label. Kubernetes wildcard hosts match exactly one label, so this does not match
+the apex, and on the deployment this chart was written for it must not: the apex
+is the marketing site, a separate application (see site/ and
+docker-compose.site.yml). extraHosts exists for a genuine second name, not for
+reclaiming the apex.
+
+Agents reach the server's gRPC port, which is plain h2c — the server holds no
+certificates of its own, TLS has always been terminated by whatever sits in
+front. Traefik will not speak h2c to a backend unless told to, and it is told
+per Service, which is why the gRPC route gets a Service of its own below rather
+than reusing the two-port one. Annotating the shared Service would force h2c on
+its HTTP port too.
+*/}}
+{{- $tls := .Values.ingress.tls }}
+{{- $webHost := required "ingress.enabled requires ingress.web.host" .Values.ingress.web.host }}
+{{- $hosts := prepend .Values.ingress.web.extraHosts $webHost }}
+{{- $apiPaths := .Values.ingress.api.paths }}
+{{- if and .Values.ingress.api.enabled (not $apiPaths) }}
+{{- fail "ingress.api.enabled requires at least one path in ingress.api.paths" }}
+{{- end }}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ .Release.Name }}-web
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: web
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: {{ .Values.ingress.entrypoint | quote }}
+    {{- if and $tls.enabled $tls.certResolver }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    traefik.ingress.kubernetes.io/router.tls.certresolver: {{ $tls.certResolver | quote }}
+    {{- else if $tls.enabled }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    {{- end }}
+    {{- with .Values.ingress.annotations }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  {{- if .Values.ingress.className }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if and $tls.enabled $tls.secretName }}
+  tls:
+    - hosts:
+        {{- range $hosts }}
+        - {{ . | quote }}
+        {{- end }}
+      secretName: {{ $tls.secretName }}
+  {{- end }}
+  rules:
+    {{- range $host := $hosts }}
+    - host: {{ $host | quote }}
+      http:
+        paths:
+          {{- /*
+            The API paths come first and, more importantly, are longer. Traefik
+            derives router priority from rule length, so Host(x) &&
+            PathPrefix(/api) outranks Host(x) && PathPrefix(/) without anyone
+            having to assign priorities by hand. Order within the list is for
+            the reader; the length is what decides.
+          */}}
+          {{- if $.Values.ingress.api.enabled }}
+          {{- range $apiPaths }}
+          - path: {{ . | quote }}
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ $.Release.Name }}-server
+                port:
+                  number: {{ $.Values.server.service.httpPort }}
+          {{- end }}
+          {{- end }}
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ $.Release.Name }}-web
+                port:
+                  number: {{ $.Values.web.service.port }}
+    {{- end }}
+{{- if .Values.ingress.grpc.enabled }}
+{{- $grpcHost := required "ingress.grpc.enabled requires ingress.grpc.host" .Values.ingress.grpc.host }}
+{{/*
+GRPC_HOST is what an agent is told to dial, and it is baked into every install
+one-liner. Left pointing at the in-cluster Service while agents are expected to
+arrive through the ingress, every install would succeed and every agent would
+fail to connect — with nothing in the control plane saying why.
+*/}}
+{{- $grpcEnv := tpl .Values.server.env.grpcHost . }}
+{{- if contains (printf "%s-server" .Release.Name) $grpcEnv }}
+{{- fail (printf "ingress.grpc.enabled routes agents through %s, but server.env.grpcHost is still the in-cluster address %q. Agents dial the value of grpcHost, so set it to the public gRPC address (for example %q)." $grpcHost $grpcEnv (printf "%s:443" $grpcHost)) }}
+{{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-server-grpc
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+  annotations:
+    # The server speaks h2c: it terminates no TLS itself. Without this Traefik
+    # dials the backend as HTTP/1.1 and every agent handshake fails.
+    traefik.ingress.kubernetes.io/service.serversscheme: h2c
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: server
+  ports:
+    - name: grpc
+      port: {{ .Values.server.service.grpcPort }}
+      targetPort: {{ .Values.server.service.grpcPort }}
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ .Release.Name }}-grpc
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: {{ .Values.ingress.entrypoint | quote }}
+    {{- if and $tls.enabled $tls.certResolver }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    traefik.ingress.kubernetes.io/router.tls.certresolver: {{ $tls.certResolver | quote }}
+    {{- else if $tls.enabled }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    {{- end }}
+    {{- with .Values.ingress.grpc.annotations }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  {{- if .Values.ingress.className }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if and $tls.enabled $tls.grpcSecretName }}
+  tls:
+    - hosts:
+        - {{ $grpcHost | quote }}
+      secretName: {{ $tls.grpcSecretName }}
+  {{- end }}
+  rules:
+    - host: {{ $grpcHost | quote }}
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ .Release.Name }}-server-grpc
+                port:
+                  number: {{ .Values.server.service.grpcPort }}
+{{- end }}
+{{- end }}

deploy/chart/vantage/templates/migrate-job.yaml

@@ -0,0 +1,68 @@
+{{- if .Values.server.migrationJob.enabled }}
+{{/*
+Schema setup, lifted out of the serving pods.
+
+Every server process used to run migrations, index builders and default-step
+seeding at boot. With one replica that is fine. With two it is not: 0004 renames
+the orgs collection to instances, and a sibling reading it mid-rename is a
+corruption, not a retry.
+
+A Helm hook Job runs it once, before any pod of the new version starts. The
+Deployment then sets VANTAGE_SKIP_MIGRATIONS, which is what makes the Job's
+existence load-bearing rather than decorative — if you disable the Job, the
+pods go back to migrating themselves and you must go back to one replica.
+
+hook-weight orders this after the dependency waits; before-hook-creation deletes
+the previous Job so a repeat upgrade is not blocked by an immutable object. The
+Job is deliberately NOT deleted on success: its logs are the record of what the
+upgrade did to the database.
+*/}}
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: {{ .Release.Name }}-migrate
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: migrate
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "0"
+    "helm.sh/hook-delete-policy": before-hook-creation
+spec:
+  backoffLimit: {{ .Values.server.migrationJob.backoffLimit }}
+  # A migration that has not finished in this long is stuck, and a stuck
+  # migration should fail the upgrade rather than hold it open forever.
+  activeDeadlineSeconds: {{ .Values.server.migrationJob.activeDeadlineSeconds }}
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: migrate
+    spec:
+      restartPolicy: Never
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      {{- if .Values.mongo.enabled }}
+      # Only Mongo. The Job never opens Redis, and waiting on a Redis this
+      # chart may not even deploy would block an upgrade for no reason.
+      initContainers:
+        - 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
+      {{- end }}
+      containers:
+        - name: migrate
+          image: "{{ .Values.server.image.repository }}:{{ .Values.server.image.tag }}"
+          env:
+            {{- include "vantage.server.env" . | nindent 12 }}
+            - name: VANTAGE_MIGRATE_ONLY
+              value: "true"
+{{- end }}

deploy/chart/vantage/templates/mongo.yaml

@@ -0,0 +1,92 @@
+{{- if .Values.mongo.enabled }}
+{{- 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 }}
+{{- end }}

deploy/chart/vantage/templates/redis.yaml

@@ -0,0 +1,92 @@
+{{- if .Values.redis.enabled }}
+{{- 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 }}
+{{- end }}

deploy/chart/vantage/templates/server.yaml

@@ -0,0 +1,174 @@
+{{- 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 := int .Values.server.replicaCount }}
+  replicas: {{ $replicas }}
+  {{- if and .Values.server.persistence.enabled (eq .Values.server.persistence.accessMode "ReadWriteOnce") }}
+  # A ReadWriteOnce volume cannot be mounted by a second pod at all, and cannot
+  # be handed to a new pod while the old one still holds it. Persistence is off
+  # by default now that nothing writes to it; if it is on, replicas are capped
+  # at one and updates go through Recreate.
+  {{- if gt $replicas 1 }}
+  {{- fail "server.persistence.enabled with a ReadWriteOnce volume cannot be combined with server.replicaCount > 1. Nothing in the server writes to that volume any more (workflow logs live in MongoDB); set server.persistence.enabled=false, or use a ReadWriteMany accessMode if you are keeping it for another reason." }}
+  {{- end }}
+  strategy:
+    type: Recreate
+  {{- end }}
+  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 }}
+      {{- if or .Values.redis.enabled .Values.mongo.enabled }}
+      # Wait for the dependencies this chart deploys to be reachable,
+      # approximating compose's `depends_on: condition: service_healthy`. An
+      # external Redis or Mongo is assumed to be up already — waiting on one
+      # would only turn someone else's outage into a stuck pod.
+      initContainers:
+        {{- if .Values.redis.enabled }}
+        - 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
+        {{- end }}
+        {{- if .Values.mongo.enabled }}
+        - 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
+        {{- end }}
+      {{- end }}
+      containers:
+        - name: server
+          image: "{{ .Values.server.image.repository }}:{{ .Values.server.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.server.service.httpPort }}
+            - containerPort: {{ .Values.server.service.grpcPort }}
+          env:
+            {{- include "vantage.server.env" . | nindent 12 }}
+            {{- if .Values.server.migrationJob.enabled }}
+            # Schema setup ran in the pre-upgrade Job. Pods that repeated it
+            # would race each other, and the rename migration is not a race
+            # that tolerates a loser.
+            - name: VANTAGE_SKIP_MIGRATIONS
+              value: "true"
+            {{- end }}
+          # Liveness never touches Mongo or Redis: restarting every pod cannot
+          # fix a database outage, and each restart drops every agent command
+          # stream and console session it was carrying. Readiness does check
+          # both, so a pod that cannot serve leaves the Service and stays up.
+          startupProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.server.service.httpPort }}
+            periodSeconds: 5
+            # Generous: without the migration Job this pod runs every migration
+            # before it listens, and the rename has a ten-minute budget.
+            failureThreshold: 150
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.server.service.httpPort }}
+            periodSeconds: 20
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: {{ .Values.server.service.httpPort }}
+            periodSeconds: 10
+            failureThreshold: 3
+          {{- if .Values.server.persistence.enabled }}
+          # Nothing in the server writes here any more — workflow logs moved to
+          # MongoDB so that every replica can read and write them. The mount
+          # remains only so an operator upgrading from a file-log release can
+          # still reach the old files before turning persistence off.
+          volumeMounts:
+            - name: server-data
+              mountPath: /data
+      volumes:
+        - name: server-data
+          persistentVolumeClaim:
+            claimName: {{ .Release.Name }}-server-data
+          {{- end }}
+---
+{{- if gt (int .Values.server.replicaCount) 1 }}
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: {{ .Release.Name }}-server
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  # Agents reconnect on their own, but a drain that took every replica at once
+  # would disconnect every agent in the fleet simultaneously and stall every
+  # workflow run in flight.
+  minAvailable: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: server
+---
+{{- 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,80 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-web
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: web
+spec:
+  # web holds no per-process state: sessions live in Redis and every request is
+  # proxied to the server. It is the one component here that scales freely.
+  replicas: {{ .Values.web.replicaCount }}
+  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 }}
+          # /healthz is served by this Next process; /api is rewritten to the
+          # server, so a probe there would report the backend's health and keep
+          # passing while this pod was wedged.
+          startupProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.web.service.port }}
+            periodSeconds: 3
+            failureThreshold: 20
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.web.service.port }}
+            periodSeconds: 20
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.web.service.port }}
+            periodSeconds: 10
+            failureThreshold: 3
+---
+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,107 @@
+# Default values for the vantage chart.
+
+redis:
+    enabled: true
+    addr: ""
+    image:
+        repository: redis
+        tag: "8"
+    persistence:
+        enabled: true
+        size: 1Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+    port: 6379
+    auth:
+        username: ""
+        password: ""
+        existingSecret: ""
+        usernameKey: username
+        passwordKey: password
+
+mongo:
+    enabled: true
+    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:
+    replicaCount: 1
+    migrationJob:
+        enabled: true
+        backoffLimit: 0
+        activeDeadlineSeconds: 900
+    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: ""
+        appRootLabel: vantage
+        proxyAdvertiseHost: "{{ .Release.Name }}-server"
+        proxyListenHost: "0.0.0.0"
+    persistence:
+        enabled: false
+        size: 1Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+        hostPath: /data
+
+web:
+    replicaCount: 1
+    image:
+        repository: gitea.hostxtra.co.uk/mrhid6/vantage/web
+        tag: latest
+    service:
+        type: ClusterIP
+        port: 3000
+    env:
+        apiUrl: "http://{{ .Release.Name }}-server:8080"
+
+ingress:
+    enabled: false
+    className: traefik
+    entrypoint: websecure
+    annotations: {}
+    web:
+        host: ""
+        extraHosts: []
+    api:
+        enabled: false
+        paths:
+            - /api
+            - /auth
+            - /update
+            - /install
+            - /update.ps1
+            - /install.ps1
+    grpc:
+        enabled: true
+        host: ""
+        annotations: {}
+    tls:
+        enabled: true
+        secretName: ""
+        grpcSecretName: ""
+        certResolver: ""
+
+imagePullSecrets: []

deploy/docker/.env.example

@@ -5,10 +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
-
-# Gitea host used to build agent install scripts and download URLs.
-GITEA_HOST=gitea.hostxtra.co.uk
+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.
@@ -21,4 +18,3 @@ KEY_ENCRYPTION_KEY=
 MONGO_URI=mongodb://mongo:27017/vantage
 
 # Where workflow run logs are written inside the server container.
-# VANTAGE_WORKFLOW_LOG_DIR=/data/workflow-logs

deploy/docker/docker-compose.site.yml

@@ -55,4 +55,13 @@ services:
             - 3004:3000
         depends_on:
             - admin
+    # Static docs, served by nginx at vantage.hostxtra.co.uk/docs through its own
+    # proxy location. That location must sort ABOVE the catch-all forwarding to
+    # site:3003, or Next serves its own 404 for /docs. The container serves from
+    # /usr/share/nginx/html/docs because the proxy forwards the full path.
+    docsite:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/docsite:latest
+        restart: unless-stopped
+        ports:
+            - 3005:80
 networks: {}

deploy/docker/docker-compose.yml

@@ -41,14 +41,12 @@ services:
         environment:
             MONGO_URI: ${MONGO_URI:-mongodb://mongo:27017/vantage}
             REDIS_ADDR: redis:6379
-            GITEA_HOST: ${GITEA_HOST}
             GRPC_HOST: ${GRPC_HOST}
             GRPC_PORT: "9090"
             HTTP_PORT: "8080"
             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
@@ -61,6 +59,8 @@ services:
         restart: unless-stopped
         ports:
             - 3000:3000
+        environment:
+            API_URL: ${API_URL:-http://server:8080}
         depends_on:
             - server
 volumes:

docs/superpowers/plans/2026-07-26-cloud-instance-creation.md

@@ -1830,7 +1830,6 @@ sleep 6
 MSYS_NO_PATHCONV=1 docker run -d --name p2-server -p 8092:8080 \
   -e MONGO_URI=mongodb://host.docker.internal:27024 -e MONGO_DB=p2 \
   -e GRPC_HOST=localhost:9090 -e REDIS_ADDR=host.docker.internal:6390 \
-  -e GITEA_HOST=example.invalid \
   --add-host host.docker.internal:host-gateway vantage-server:p2
 sleep 6
 MSYS_NO_PATHCONV=1 docker logs p2-server 2>&1 | grep -i reaper
@@ -2012,7 +2011,6 @@ MSYS_NO_PATHCONV=1 docker rm -f p2-server
 MSYS_NO_PATHCONV=1 docker run -d --name p2-server -p 8092:8080 \
   -e MONGO_URI=mongodb://host.docker.internal:27024 -e MONGO_DB=p2 \
   -e GRPC_HOST=localhost:9090 -e REDIS_ADDR=host.docker.internal:6390 \
-  -e GITEA_HOST=example.invalid -e FREE_INSTANCE_REAP_AFTER=336h \
   --add-host host.docker.internal:host-gateway vantage-server:p2
 sleep 6
 MSYS_NO_PATHCONV=1 docker logs p2-server 2>&1 | grep -i reaper

docs/superpowers/plans/2026-07-26-cloud-instance-identity.md

@@ -780,7 +780,6 @@ Expected: output includes `email_1`. This reproduces a database that predates th
 MSYS_NO_PATHCONV=1 docker run -d --name vantage-idx-server -p 8091:8080 \
   -e MONGO_URI=mongodb://host.docker.internal:27023 -e MONGO_DB=vantage_idx \
   -e GRPC_HOST=localhost:9090 -e REDIS_ADDR=host.docker.internal:6389 \
-  -e GITEA_HOST=example.invalid \
   --add-host host.docker.internal:host-gateway vantage-server:test
 
 MSYS_NO_PATHCONV=1 docker run --rm --add-host host.docker.internal:host-gateway mongo:7 \

docs/superpowers/specs/2026-07-28-docs-site-design.md

@@ -0,0 +1,162 @@
+# Documentation site — design
+
+**Date:** 2026-07-28
+**Status:** approved
+
+## Problem
+
+Vantage has no user-facing documentation. Everything an operator needs — how to
+install self-hosted, how to enrol an agent, what a workflow step is, how a
+licence gets issued — lives either in `CLAUDE.md` (written for contributors, not
+users) or in the code. The marketing site sells the product and the control
+plane runs it; neither explains it.
+
+## Solution
+
+A fourth Next-adjacent frontend, `docsite/`, built with Docusaurus v3 and shipped
+alongside the marketing site.
+
+### Placement and deployment
+
+- Lives at repo root as `docsite/`.
+- Served at **`vantage.hostxtra.co.uk/docs`** — a path on the marketing site's
+  host, routed by a separate Nginx Proxy Manager custom location rather than by
+  `site/`. It is a path, not a subdomain, deliberately: `*.vantage.hostxtra.co.uk`
+  is the per-tenant instance namespace and `APP_ROOT_LABEL` resolves an org from
+  the label before `vantage`, so a `docs.` label there would be read as a tenant
+  slug.
+
+  This makes `baseUrl: "/docs/"` load-bearing. An NPM custom location forwards
+  the **full** request path upstream — it does not strip the `/docs` prefix — so
+  the container serves the build from `/usr/share/nginx/html/docs`, not from the
+  document root. Prefix, asset URLs and upstream paths then agree with no
+  rewrite rule to keep in step. Getting this wrong is quiet: the HTML loads and
+  every stylesheet and script 404s.
+- Added to **`deploy/docker-compose.site.yml` only**, published as `3005`.
+  `deploy/docker-compose.yml` (the self-hosted install) must never mention it,
+  exactly as it never mentions `site`, `sitesvc`, `admin` or `adminsite`.
+- Added to `.gitea/workflows/server-deploy.yml` as a seventh image, rebuilding
+  on `^docsite/` only, build context `docsite/`.
+
+### Runtime
+
+Docusaurus emits a fully static site, so unlike `site/`, `web/` and
+`adminsite/` there is no Node server at runtime. Two stages:
+
+1. `node:26-alpine` builder — `npm ci && npm run build` → `/app/build`.
+2. `nginx:alpine-slim` runner — copies `build/` to
+   `/usr/share/nginx/html/docs` (see the `/docs` prefix note above), plus a
+   small `nginx.conf` giving `try_files` a 404 fallback to Docusaurus's
+   `404.html` and long cache headers on `/docs/assets/`. A bare `/` request
+   redirects to `/docs/`, so hitting the container directly is not a blank 403.
+
+`nginx:alpine-slim` is roughly 12MB against `caddy:alpine`'s ~50MB, and nothing
+here needs Caddy's automatic TLS — the host proxy already terminates it.
+
+Build args, baked at build time the same way `site/`'s are:
+
+| Arg | Purpose |
+| --- | --- |
+| `DOCS_URL` | site `url`; defaults to `https://vantage.hostxtra.co.uk` |
+| `DOCS_BASE_URL` | site `baseUrl`; defaults to `/docs/`. Must match the NPM location and the runner's copy target |
+| `APP_URL` | navbar link to the control plane |
+| `HQ_URL` | navbar link to the HQ portal |
+
+### Theme
+
+`docsite/src/css/custom.css` carries `site/app/globals.css`'s token blocks
+**copied verbatim** — same names, same values — and maps Docusaurus's `--ifm-*`
+variables onto them. Docusaurus stamps `data-theme="light|dark"` on `<html>`,
+which is the same selector `site/`'s dark block already keys on, so the built-in
+toggle works with no extra wiring. Light is the default, matching `site/` and
+`adminsite/`.
+
+This makes a **fifth** copy of the token block (`site/`, `adminsite/`, `web/`
+dark-only, `shared/mail/templates/layout.html.tmpl` as literal hex, and now
+`docsite/`). Nothing enforces the match; `CLAUDE.md`'s Frontend section is
+updated to say so. No component in `docsite/` may carry a hex value.
+
+Search is `@easyops-cn/docusaurus-search-local` — index built at compile time,
+served from the same origin. No Algolia account, no external host, nothing to
+key or rotate.
+
+Docs-only mode: `routeBasePath: "/"`, blog disabled, no tutorial scaffolding.
+
+## Content
+
+Sidebar is authored explicitly in `sidebars.ts` rather than autogenerated, so
+ordering is a decision rather than a filename accident.
+
+### Getting Started
+
+| Page | Covers |
+| --- | --- |
+| `what-is-vantage` | The control plane, the agent, what problem each solves |
+| `cloud-vs-self-hosted` | The two deployments, what differs (licensing, HQ-managed users, reaping) |
+| `self-hosted-install` | Prereqs (Docker, external MongoDB, DNS, TLS), `docker-compose.yml`, required env, `docker compose up -d` |
+| `first-login` | `/setup` bootstrap, first org and owner |
+| `first-server` | `POST /servers/new`, the install one-liner, Linux and Windows, watching it flip to `active` |
+| `claim-free-licence` | Linking the install to an HQ account, `claim-free` |
+
+`self-hosted-install` is the page the section exists for; it names every
+required environment variable with its consequence-of-omission, in particular
+`GRPC_HOST` (boot fails, no default is safe) and `KEY_ENCRYPTION_KEY`.
+
+### Vantage (the application)
+
+`servers` (agent install Linux/Windows, inventory, OS updates, agent
+self-update) · `ssh-keys` (upload, generate-on-server, assign, revoke, what the
+agent writes and when) · `workflows` (step library, default steps and why they
+are read-only, the designer, running, live logs, `on_failure`, `output_env`,
+workspaces, log retention) · `monitors` (the four check types, server vs agent
+runner, retries, incidents, uptime rollups) · `notification-channels` (five
+types, testing) · `secrets` (vault, `secret_refs` in steps, the ESO read path
+and its bearer token) · `browser-console` (SSH/RDP/VNC, one-time tokens) ·
+`audit-log` · `settings` (members and roles, OIDC per org, retention, ESO token,
+licence).
+
+### Vantage HQ (the portal)
+
+`accounts-and-signup` (account-first signup, email verification, an account is
+a team) · `people-and-roles` (owner/admin/member, invitations, accepting) ·
+`cloud-instances` (create, overview, granting members and what a grant actually
+is) · `self-hosted-instances` (purchase creates a placeholder, claim-link binds
+the real UUID, relink) · `licensing-and-entitlements` (tiers, metered server
+count, feature toggles, desired vs granted) · `billing` (Paddle as merchant of
+record, checkout, the customer portal, changing configuration) · `free-tier`
+(limits, the renewal window, reaping on cloud).
+
+### Reference
+
+`environment-variables` (server, sitesvc, admin, agent) · `rest-api` (the route
+tables, grouped as in `CLAUDE.md`) · `grpc-api` (the eight RPCs, the command
+stream) · `agent-config` (config.yaml, paths, permissions) ·
+`ports-and-networking` (which ports, which direction, what needs to be
+reachable) · `troubleshooting`.
+
+### Operations
+
+`upgrading` (pull and recreate) · `backups` (MongoDB is the durable state; Redis
+is sessions only) · `agent-updates` · `ci-cd` (which image rebuilds when, and
+the repo-variable gap that pushes no commit).
+
+## Writing rules
+
+- Every guide is task-shaped: numbered steps, real paths and commands taken from
+  the repository, never invented UI.
+- Behaviour that is a hard refusal gets an admonition, not a paragraph: default
+  steps are read-only (409 `ErrDefaultStep`), `POST /license` answers 409
+  `cloud_managed` on cloud, HQ-sourced users cannot have their role changed
+  locally (409 `ErrHQManaged`).
+- Where the UI enforces something, say that the API is the boundary and the UI
+  is the courtesy — the same phrasing the codebase uses.
+- No screenshots in this pass. They rot faster than prose and there is no
+  capture pipeline.
+
+## Out of scope
+
+- Versioned documentation. One version, tracking `main`. Docusaurus versioning
+  can be switched on later without restructuring.
+- Internationalisation.
+- Screenshots and diagrams beyond what Mermaid renders inline.
+- A docs search backed by an external service.

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/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+build
+.docusaurus
+.git
+.gitignore

docsite/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+build
+.docusaurus
+.cache-loader

docsite/Dockerfile

@@ -0,0 +1,40 @@
+# Build stage
+FROM node:26-alpine AS builder
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm install
+
+COPY . .
+
+# Baked in at build time. DOCS_BASE_URL must agree with three things at once:
+# the Nginx Proxy Manager location that routes to this container, the directory
+# the runtime stage serves from below, and this value. When they disagree the
+# HTML loads and every stylesheet and script 404s.
+ARG DOCS_URL="https://vantage.hostxtra.co.uk"
+ARG DOCS_BASE_URL="/docs/"
+ARG APP_URL="https://vantage.hostxtra.co.uk"
+ARG HQ_URL="https://vantage-hq.hostxtra.co.uk"
+ENV DOCS_URL=$DOCS_URL
+ENV DOCS_BASE_URL=$DOCS_BASE_URL
+ENV APP_URL=$APP_URL
+ENV HQ_URL=$HQ_URL
+
+RUN npm run build
+
+# Runtime stage
+#
+# Docusaurus emits a fully static site, so unlike web/, site/ and adminsite/
+# there is no Node server at runtime. alpine-slim is roughly a quarter the size
+# of caddy:alpine, and nothing here needs automatic TLS — the host proxy
+# terminates it.
+FROM nginx:alpine-slim AS runner
+
+# NPM forwards the FULL request path upstream; it does not strip the /docs
+# prefix. Serving from a matching subdirectory means prefix, asset URLs and
+# upstream paths agree with no rewrite rule to keep in step.
+COPY --from=builder /app/build /usr/share/nginx/html/docs
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80

docsite/docs/getting-started/claim-free-licence.md

@@ -0,0 +1,80 @@
+---
+id: claim-free-licence
+title: Claim a Free licence
+sidebar_label: Claim a Free licence
+---
+
+A self-hosted install runs unlicensed until you give it a licence. Free is a
+real tier in both deployments, and you can claim one for your install from the
+HQ portal.
+
+## What a licence is
+
+A signed file. It carries the instance UUID it belongs to, the tier, the server
+allowance, feature toggles and an expiry. The control plane verifies the
+signature locally checking a licence never contacts HQ, and a running instance
+does not need HQ to be reachable.
+
+Signing happens in exactly one place, in HQ. The control plane can only verify.
+
+## 1. Find your instance UUID
+
+In the control plane, go to **Settings → Licence**. The instance UUID is shown
+there. It is the identity your licence binds to.
+
+## 2. Link the install to your HQ account
+
+1. Sign in at [Vantage HQ](https://vantage-hq.hostxtra.co.uk). If you have no
+   account, see [Accounts and signup](../hq/accounts-and-signup.md).
+2. Choose **Link an instance**.
+3. Paste the instance UUID and give it a name you will recognise.
+
+Linking claims the UUID for your account. A UUID already linked elsewhere is
+refused with a conflict rather than silently moved.
+
+## 3. Claim Free
+
+With the instance linked, choose **Claim Free** on it. HQ issues a Free licence
+bound to that UUID and hands it back.
+
+:::info One Free per account, per deployment
+The limit is enforced per account **and** deployment, so a Free cloud instance
+does not stop you claiming Free on a self-hosted install. Both the friendly
+pre-check and the issuer apply the same rule deliberately, because a
+pre-check stricter than the issuer would refuse something that would actually
+have worked.
+:::
+
+## 4. Install the licence
+
+Download the licence from HQ and paste it in the control plane at
+**Settings → Licence**.
+
+The instance validates the signature, checks the UUID matches its own, and
+starts reporting the tier, allowance and expiry.
+
+:::warning Cloud instances cannot paste a licence
+On a cloud instance `POST /license` answers `409 cloud_managed`, and the UI
+hides the form entirely. A cloud licence is written directly by HQ. This is not
+a restriction the injection path has to work around it writes to the database,
+not through the endpoint.
+:::
+
+## Renewing
+
+Free licences are renewable from HQ within a renewal window near expiry;
+outside that window the renew call refuses. See [Free tier](../hq/free-tier.md).
+
+Pasting a licence keeps working while the current one is expired that endpoint
+is exempt from the licence check, because it is the way out of degraded mode.
+
+## Moving the install to new hardware
+
+Rebuilding produces a new instance UUID, and a licence binds to a UUID. Use
+**Relink** in HQ to move the licence across. The number of relinks per term is
+capped; the portal shows how many you have left.
+
+## Next
+
+- [Licensing and entitlements](../hq/licensing-and-entitlements.md)
+- [Buying a paid self-hosted licence](../hq/self-hosted-instances.md)

docsite/docs/getting-started/cloud-vs-self-hosted.md

@@ -0,0 +1,67 @@
+---
+id: cloud-vs-self-hosted
+title: Cloud or self-hosted
+sidebar_label: Cloud or self-hosted
+---
+
+Vantage runs in two deployments. They are the same software; what differs is
+who operates it and how licensing, users and data lifecycle work.
+
+## At a glance
+
+|                       | Cloud                                               | Self-hosted                    |
+| --------------------- | --------------------------------------------------- | ------------------------------ |
+| Who runs it           | We do                                               | You do                         |
+| Where you sign in     | `<your-slug>.vantage.hostxtra.co.uk`                | Your own hostname              |
+| Database and backups  | Ours                                                | Yours                          |
+| Licence               | Written for you when you buy or create the instance | Pasted in, or claimed from HQ  |
+| Team members          | Granted from HQ; the instance holds a projection    | Created in the instance itself |
+| Free tier             | Yes, one per account                                | Yes, one per account           |
+| Expired Free instance | Eventually deleted, after warning                   | Never deleted                  |
+
+## Cloud
+
+You create an instance from the HQ portal and it exists a few seconds later,
+already licensed. People you grant access to get a real user inside that
+instance see [People and roles](../hq/people-and-roles.md) but HQ owns their
+password, role and existence.
+
+:::info The instance does not phone home
+A grant writes a user row into the control plane once. After that the instance
+authenticates that person entirely on its own. HQ being down does not stop
+anyone signing in to a running instance.
+:::
+
+Cloud instances on the Free tier are reaped after their licence expires, with
+warning emails first. See [Free tier](../hq/free-tier.md).
+
+## Self-hosted
+
+You run the Docker Compose stack on your own infrastructure. Nothing about the
+control plane requires an internet connection to HQ at runtime a licence is a
+signed file, verified locally.
+
+Two ways to get one:
+
+1. **Free** link the install to an HQ account and claim it
+   ([Claim a Free licence](./claim-free-licence.md)).
+2. **Paid** buy from HQ, which creates a placeholder, then paste the install's
+   real instance UUID to bind and issue
+   ([Self-hosted instances](../hq/self-hosted-instances.md)).
+
+Self-hosted users are local (or OIDC). There is no projection from HQ, and the
+three member endpoints in HQ refuse to touch a self-hosted instance at all.
+
+## Which should you pick
+
+Pick cloud if you want the thing running now and do not want to own a MongoDB.
+Pick self-hosted if your policy requires the control plane inside your own
+network, or the servers you manage cannot reach the public internet.
+
+Moving between them is a migration, not a switch instances are bound to a
+deployment at creation, and a licence binds to an instance UUID.
+
+## Next
+
+- [Self-hosted install](./self-hosted-install.md)
+- [Accounts and signup](../hq/accounts-and-signup.md) if you are going cloud

docsite/docs/getting-started/first-login.md

@@ -0,0 +1,75 @@
+---
+id: first-login
+title: First login
+sidebar_label: First login
+---
+
+A fresh install has no users and no organisation. The first visit creates both.
+
+## 1. Bootstrap
+
+Open the control plane in a browser. Because no user exists, you land on
+`/setup`.
+
+Fill in:
+
+| Field             | Notes                                                             |
+| ----------------- | ----------------------------------------------------------------- |
+| Organisation name | Display name. Shown throughout the UI                             |
+| Slug              | Lowercase, used in the hostname on cloud. Some names are reserved |
+| Your name         |                                                                   |
+| Email             | Becomes your sign-in identity                                     |
+| Password          | Stored bcrypt-hashed                                              |
+
+Submitting creates the organisation and its **owner** you.
+
+:::warning Bootstrap works exactly once
+The endpoint is open only while the database has no users. As soon as the first
+one exists, `/setup` redirects to the login page and the bootstrap endpoint
+refuses. There is no second chance to create the first owner, so record the
+credentials before you close the tab.
+:::
+
+## 2. Sign in
+
+You are taken to `/login`. Sign in with the email and password you just set.
+
+Sessions are an opaque 32-byte token in the `km_session` cookie, with the body
+held in Redis for 24 hours. Restarting Redis signs everyone out and loses
+nothing else.
+
+## 3. Look around
+
+You land on the fleet dashboard, which is empty. The sidebar is the whole
+product:
+
+| Section   | What it does                              |
+| --------- | ----------------------------------------- |
+| Servers   | The fleet enrol, inspect, console, update |
+| Keys      | SSH public keys and their assignments     |
+| Workflows | Compose and run scripted work             |
+| Steps     | The reusable step library                 |
+| Monitors  | HTTP, TCP, ICMP and TLS checks            |
+| Secrets   | The encrypted vault                       |
+| Audit     | Every mutating action                     |
+| Settings  | Members, SSO, alerts, retention, licence  |
+
+## 4. Add the rest of your team
+
+Go to **Settings → Access**. Add members with a role:
+
+| Role     | Can                                                |
+| -------- | -------------------------------------------------- |
+| `owner`  | Everything, including billing-adjacent settings    |
+| `admin`  | Everything except owner-only settings              |
+| `member` | Day-to-day work servers, keys, workflows, monitors |
+
+Settings and organisation management require `owner` or `admin`.
+
+If you would rather not manage passwords, configure OIDC instead see
+[Settings](../vantage/settings.md#single-sign-on-oidc). OIDC is configured per
+organisation, and the client secret is stored encrypted.
+
+## Next
+
+[Add your first server](./first-server.md).

docsite/docs/getting-started/first-server.md

@@ -0,0 +1,111 @@
+---
+id: first-server
+title: Add your first server
+sidebar_label: Add your first server
+---
+
+Enrolling a machine means running one command on it. The control plane issues a
+short-lived token, the install script fetches the agent and writes a config, and
+the machine registers itself.
+
+## 1. Create the enrolment
+
+In the UI, go to **Servers → Add server**. That calls `POST /api/servers/new`,
+which generates a server ID and a pre-registration token and hands back a ready
+one-liner.
+
+:::warning The token is single-use and lives one hour
+It is the only credential in the flow, and it is spent the moment the agent
+calls `Register`. If you paste it somewhere and come back tomorrow, create a new
+enrolment instead nothing is lost by doing so.
+:::
+
+## 2. Run the one-liner
+
+### Linux
+
+```bash
+curl -fsSL "https://vantage.example.com/install?server_id=<id>&token=<token>" | bash
+```
+
+Run it as root. The script:
+
+1. Detects architecture `x86_64` and `aarch64` only; anything else exits.
+2. Asks the Gitea API for the newest `agent/v*` release.
+3. Downloads the binary and `checksums.txt`, and **verifies the SHA-256**,
+   aborting on a mismatch.
+4. Installs to `/usr/local/bin/vantage-agent`, mode `0755`.
+5. Writes `/etc/vantage/config.yaml` (directory `0700`, file `0600`) containing
+   the server ID, the pre-registration token and the gRPC host.
+6. Writes `/etc/systemd/system/vantage-agent.service` with `Restart=always`, and
+   runs `systemctl enable --now vantage-agent`.
+
+### Windows
+
+```powershell
+irm "https://vantage.example.com/install.ps1?server_id=<id>&token=<token>" | iex
+```
+
+Run from an elevated PowerShell. The agent is registered as a service through
+NSSM, with the config at `%ProgramData%\vantage\config.yaml`. There is also an
+MSI built by CI if you would rather deploy that.
+
+:::info Windows agents are second-class on purpose
+They register, heartbeat, run workflow steps and report inventory. They do
+**not** manage `authorized_keys` the key subsystem is Linux-only, and a
+Windows agent stops after the heartbeat portion of the poll.
+:::
+
+## 3. Watch it come up
+
+The server appears immediately as `pending`. Within one poll interval 30
+seconds it flips to `active`.
+
+On the machine:
+
+```bash
+systemctl status vantage-agent
+journalctl -u vantage-agent -f
+```
+
+What happens on that first run:
+
+```
+1. Load /etc/vantage/config.yaml
+2. pre_reg_token present  → register → save agent_token, clear pre_reg_token
+3. Reconnect with the permanent token
+4. Start: command stream · hourly update check · inventory · monitors
+5. Enter the key poll loop
+```
+
+After registration the config no longer contains the pre-registration token; it
+contains a permanent agent token instead. The control plane stores only the
+SHA-256 of that token, never the token itself.
+
+## 4. Confirm it works
+
+Open the server's detail page. Within a minute or two you should see:
+
+- Status `active`, with a recent last-seen timestamp.
+- Inventory CPU, memory, swap, partitions, kernel. Metrics refresh every 30
+  seconds; the full static snapshot every 15 minutes.
+- Pending OS updates, checked hourly.
+
+## If it does not appear
+
+| Symptom                                    | Cause                                                                                                                             |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| Script exits at "Unsupported architecture" | Not amd64 or arm64                                                                                                                |
+| "Checksum mismatch!"                       | Interrupted download, or a proxy rewriting the body. Re-run                                                                       |
+| "Could not determine latest agent version" | The host cannot reach `gitea.hostxtra.co.uk`, or no `agent/v*` release exists                                                     |
+| Service runs, server stays `pending`       | The machine cannot reach `GRPC_HOST`. Test it from that machine                                                                   |
+| Registers once then goes `offline`         | Reachable for `Register` but not for the poll usually a firewall that permits the initial connection but drops the long-lived one |
+
+A server is marked `offline` when its last-seen time passes the threshold; that
+sweep runs every two minutes, so allow for it before concluding anything.
+
+## Next
+
+- [Assign an SSH key](../vantage/ssh-keys.md)
+- [Run a workflow](../vantage/workflows.md)
+- [Claim a Free licence](./claim-free-licence.md)

docsite/docs/getting-started/self-hosted-install.md

@@ -0,0 +1,135 @@
+---
+id: self-hosted-install
+title: Install Vantage (self-hosted)
+sidebar_label: Self-hosted install
+---
+
+This installs the control plane on a host you own. Budget about fifteen minutes.
+
+## Before you start
+
+You need:
+
+- A Linux host with **Docker** and the **Compose plugin**.
+- A DNS name pointing at it. You will use it for both the web UI and, with a
+  port, for agents.
+- A reverse proxy terminating TLS in front of the web UI. gRPC on `:9090` is
+  reached directly by agents.
+- Two ports reachable from every machine you intend to manage: the web port for
+  people, and **9090** for agents.
+- Outbound access from the control plane, and from every managed machine, to
+  `gitea.hostxtra.co.uk`, which serves the agent releases.
+
+The stack itself brings MongoDB, Redis and guacd with it. You do not need to
+provide a database.
+
+## 1. Get the compose file
+
+Put `deploy/docker-compose.yml` from the repository in a working directory, for
+example `/opt/vantage`.
+
+```bash
+mkdir -p /opt/vantage/data && cd /opt/vantage
+# copy docker-compose.yml here
+```
+
+The `server` service bind-mounts `./data`, which is where workflow run logs are
+written. Create it before first boot so it is not owned by root-in-container in
+a way you did not intend.
+
+## 2. Write the environment file
+
+Create `/opt/vantage/.env`:
+
+```bash
+# The host:port agents dial. NOT the web URL this port speaks gRPC.
+GRPC_HOST=vantage.example.com:9090
+
+
+# 32 bytes as 64 hex characters. Generate with the command below.
+KEY_ENCRYPTION_KEY=
+
+# Optional: where workflow run logs are written inside the container.
+```
+
+Generate the encryption key:
+
+```bash
+openssl rand -hex 32
+```
+
+:::danger Keep the encryption key
+`KEY_ENCRYPTION_KEY` encrypts SSH private keys, vault secrets, OIDC client
+secrets and console credentials with AES-256-GCM. Lose it and every one of those
+becomes unreadable there is no recovery path. Back it up somewhere other than
+the server it protects, and never rotate it without a planned re-encryption.
+:::
+
+:::warning `GRPC_HOST` has no default
+The server refuses to boot without it. There is deliberately no fallback to the
+web host: that would hand every agent a port that does not speak gRPC, and the
+failure would only surface later, on each agent, as a connection error.
+:::
+
+## 3. Start the stack
+
+```bash
+docker compose up -d
+docker compose ps
+```
+
+Five services come up: `mongo`, `redis`, `guacd`, `server` and `web`.
+
+Check the server got through boot:
+
+```bash
+docker compose logs -f server
+```
+
+Boot runs database migrations, builds indexes and seeds the default workflow
+step library. Index builders for auth and settings are **fatal on failure** —
+they enforce tenant isolation, so the server would rather not start than start
+without them.
+
+## 4. Put a proxy in front
+
+Point your reverse proxy at `web` on port `3000` and terminate TLS there. The
+web app calls the REST API through a Next rewrite, so you do not need to expose
+`8080` publicly.
+
+Do **not** proxy `9090`. Agents connect to it directly over TLS.
+
+## 5. First sign-in
+
+Open your hostname in a browser. With no users in the database, you are sent to
+`/setup`.
+
+Continue with [First login](./first-login.md).
+
+## Verifying the install
+
+| Check                                          | Expected                        |
+| ---------------------------------------------- | ------------------------------- |
+| `docker compose ps`                            | five services `running`         |
+| `curl -s localhost:8080/auth/bootstrap-status` | JSON saying bootstrap is needed |
+| `nc -z your-host 9090`                         | open                            |
+| `docker compose logs server \| grep -i fatal`  | nothing                         |
+
+## Common install problems
+
+**Server exits immediately.** Almost always a missing `GRPC_HOST`. The log line
+names it.
+
+**Agents register but never go active.** They reached `:9090` for `Register` but
+cannot sustain the poll, or `GRPC_HOST` names a host they resolve differently.
+Check from the managed machine, not from the control plane host.
+
+**Secrets pages error.** `KEY_ENCRYPTION_KEY` is empty or not 64 hex characters.
+
+More in [Troubleshooting](../reference/troubleshooting.md).
+
+## What this install does not include
+
+The website, the HQ portal and this documentation site are hosted by us and are
+not part of a self-hosted install. It deliberately runs none of them, and in
+particular never holds the licence signing key.

docsite/docs/getting-started/what-is-vantage.md

@@ -0,0 +1,63 @@
+---
+id: what-is-vantage
+title: What is Vantage
+sidebar_label: What is Vantage
+---
+
+Vantage manages a fleet of servers from one place. It began as SSH key
+management and grew outwards: key assignment, scripted workflow execution,
+service monitoring, a secrets vault, a browser-based console and OS update
+management.
+
+## The pieces
+
+```mermaid
+flowchart TD
+    W["Web UI<br/>servers · keys · workflows · monitors<br/>secrets · audit · console · settings"]
+    S["Server<br/>REST :8080 · gRPC :9090<br/>MongoDB · Redis · guacd"]
+    A["Agent<br/>one per managed server<br/>Linux and Windows"]
+    W -->|REST, cookie session| S
+    S -->|gRPC over TLS| A
+    A -.->|outbound only| S
+```
+
+**The server** holds all state and does all decision-making. It exposes a REST
+API on `:8080` for the web UI and a gRPC API on `:9090` for agents. MongoDB
+stores everything durable; Redis stores sessions and nothing else.
+
+**The agent** is a single Go binary running as root on each managed server. It
+polls the control plane every 30 seconds for desired key state, and holds a
+bidirectional command stream so the server can push work run a workflow step,
+generate a key, apply updates without waiting for the next poll.
+
+**The web UI** is the operator interface. Everything it does goes through the
+REST API, which is the actual security boundary; the UI only ever makes things
+convenient.
+
+## How agents connect
+
+The agent dials **out** to the control plane. There is no inbound listener on a
+managed server, no port to open and no NAT traversal to arrange. If the machine
+can reach your Vantage host on the gRPC port, it can be managed.
+
+That direction is why `GRPC_HOST` exists as an explicit setting: the agent has
+to be told a `host:port` it can reach, and there is no safe default the server
+could guess on its behalf.
+
+## Two request patterns
+
+| Pattern                       | Used for                                                   | Why                                                                                              |
+| ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| Poll, every 30s               | desired SSH key state                                      | Key changes are not urgent, and polling survives a dropped connection with no reconnection logic |
+| Push, over the command stream | workflow steps, key generation, updates, agent self-update | Clicking Run should not wait up to 30 seconds                                                    |
+
+## Multi-tenancy
+
+Every document in the database carries an instance ID, and every query is scoped
+by it. One deployment can therefore host many independent tenants. On a
+self-hosted install that mechanism is still there you simply have one tenant.
+
+## Next
+
+- [Cloud or self-hosted](./cloud-vs-self-hosted.md) which one you want
+- [Self-hosted install](./self-hosted-install.md) stand it up

docsite/docs/hq/accounts-and-signup.md

@@ -0,0 +1,78 @@
+---
+id: accounts-and-signup
+title: Accounts and signup
+sidebar_label: Accounts and signup
+---
+
+Vantage HQ, at `vantage-hq.hostxtra.co.uk`, is where you manage the **account**
+behind your instances: your team, your instances, their licences and billing.
+
+## An account is a team, not a person
+
+One account holds many people and many instances. Everyone in it has an account
+role:
+
+| Role     | Can                                                    |
+| -------- | ------------------------------------------------------ |
+| `owner`  | Everything, including billing                          |
+| `admin`  | Invite people, create instances, grant instance access |
+| `member` | Read what the account holds                            |
+
+Reading is open to any signed-in member. Every mutation except changing your own
+password requires `owner` or `admin`. Billing is owner-only.
+
+The three words are the same as the control plane's roles, on purpose but they
+are separate things. Your account role governs the portal; your role _inside_ an
+instance governs that instance.
+
+## Signing up
+
+Signup is **account-first**. Creating an account creates the account and you;
+it does not create a Vantage instance. Nothing exists in any control plane until
+you later create or link one.
+
+1. Go to the signup form.
+2. Enter your name, email and a password.
+3. Check your email and click the verification link.
+
+:::info Verify before you can sign in
+An unverified account gets a distinct "check your email" message rather than a
+generic authentication failure the address is already known to be yours, so
+there is nothing to protect by being vague.
+:::
+
+Verification links are valid for **24 hours**. The token is 32 random bytes and
+only its SHA-256 hash is stored, so a leaked database yields no working links.
+
+If the verification email cannot be sent, the signup is rolled back rather than
+left stranded retry rather than assuming a half-created account is in the way.
+
+## Signing in
+
+Email and password. The session is a cookie, separate from the control plane's:
+signing in to HQ does not sign you in to an instance, and vice versa.
+
+## What comes next
+
+| You want                       | Go to                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| A Vantage instance we run      | [Cloud instances](./cloud-instances.md)                       |
+| To license an install you run  | [Self-hosted instances](./self-hosted-instances.md)           |
+| To add colleagues              | [People and roles](./people-and-roles.md)                     |
+| To understand tiers and limits | [Licensing and entitlements](./licensing-and-entitlements.md) |
+
+## The portal layout
+
+Three destinations: **Overview**, **People**, **Billing**.
+
+Settings lives in the account menu rather than the nav, because it is your
+password rather than a place. The appearance toggle is there too.
+
+Overview lists your instances. Each is one record, closed to a row and open to
+its licence contents, members and actions. It opens by default when it is your
+only instance or when it needs attention, and your manual choice is remembered.
+
+There is deliberately no "your plan" card in the sidebar: tier, limits and
+expiry belong to a **licence**, and a licence belongs to one instance. An
+account with a Free cloud instance and a Professional self-hosted one has no
+single plan to show.

docsite/docs/hq/billing.md

@@ -0,0 +1,83 @@
+---
+id: billing
+title: Billing
+sidebar_label: Billing
+---
+
+Paid plans are billed through **Paddle**, which is the merchant of record. Your
+invoice, your card details and your tax handling are all Paddle's; HQ holds a
+customer reference and nothing sensitive.
+
+Billing is **owner-only**.
+
+## Buying
+
+### Cloud
+
+Open the instance, change its configuration to what you want, and check out.
+Checkout runs in the browser.
+
+### Self-hosted
+
+**Buy self-hosted**, then bind the purchase to your install's UUID. See
+[Self-hosted instances](./self-hosted-instances.md).
+
+## What you are buying
+
+A subscription's line items are the configuration: the plan base, the metered
+server count above the base, and any per-instance features. Changing the
+configuration changes the line items.
+
+## Changing configuration
+
+**Instance → Configuration**, adjust servers or features, and save.
+
+- **Increases** take effect when the payment confirms.
+- **Reductions** are scheduled for the end of the term. The portal shows the
+  date and the new value.
+
+## The customer portal
+
+**Billing → Manage** mints a Paddle customer-portal session where you can
+update your payment method, see invoices and cancel.
+
+## How a licence follows a payment
+
+```mermaid
+flowchart LR
+    C["Checkout / change"] --> P["Paddle"]
+    P -->|signed webhook| H["HQ"]
+    H --> G["Entitlement: desired → granted"]
+    G --> L["Licence signed from granted"]
+```
+
+The webhook is the **only** issuing path for paid plans. It is signature
+verified, processed exactly once, and resolved from the subscription's _current_
+line items so a webhook that arrives out of order still produces the right
+answer rather than replaying a stale state.
+
+A licence is signed from **granted** only. A checkout you abandon changes
+nothing.
+
+## Cancelling and failed payments
+
+Cancelling, or a payment going past due, takes **no immediate licence action**.
+Your licence runs to its grace-padded expiry and then lapses normally. There is
+no mid-term cut-off.
+
+For a cloud Free instance, lapsing eventually leads to deletion see
+[Free tier](./free-tier.md). Paid instances are not reaped.
+
+## Renewals
+
+At renewal the subscription bills again and the licence is reissued for the new
+term. It is also the only moment a scheduled **reduction** takes effect.
+
+Self-hosted customers: download and paste the reissued licence. Cloud customers:
+nothing to do.
+
+## Free is not in Paddle at all
+
+Free has no subscription, no £0 line item and no Paddle record. It has its own
+renewal, in the portal. An account only acquires a Paddle customer reference
+with its first paid purchase.

docsite/docs/hq/cloud-instances.md

@@ -0,0 +1,78 @@
+---
+id: cloud-instances
+title: Cloud instances
+sidebar_label: Cloud instances
+---
+
+A cloud instance is a Vantage control plane we run for you, reachable at
+`<your-slug>.vantage.hostxtra.co.uk`.
+
+## Creating one
+
+1. **Overview → New instance**.
+2. Choose a name and a slug.
+3. Create.
+
+The instance is provisioned with you as its owner, and a Free licence is issued
+immediately. The owner user inside it gets your HQ password hash **copied**, not
+shared see [People and roles](./people-and-roles.md).
+
+### Slugs
+
+The slug becomes your hostname label, so it is lowercase, and some names are
+reserved. Pick something you can say on a phone call.
+
+:::warning One Free instance per account, per deployment
+Creating a second Free cloud instance is refused. If you want another, it needs
+a paid plan or free up the first.
+:::
+
+## Using it
+
+Sign in at your instance's hostname with the email and password you use for HQ.
+It is a normal Vantage install from that point: see
+[Getting started](../getting-started/first-login.md) and the
+[Vantage](../vantage/servers.md) section.
+
+The instance does not depend on HQ at runtime. HQ being unreachable does not
+affect anyone signing in or any agent syncing.
+
+## The instance record
+
+Each instance on Overview is one record. Closed, it is a row. Open, it shows:
+
+- **Licence contents** tier, server allowance, features, expiry.
+- **Members** who has access and with what instance role.
+- **Actions** grant access, change configuration, renew.
+
+## Members
+
+Granting access writes a real user into the instance. Covered fully in
+[People and roles](./people-and-roles.md).
+
+## Changing what it can do
+
+Server allowance and per-instance features (browser console, single sign-on) are
+part of the instance's **entitlement**. Changing it goes through billing see
+[Licensing and entitlements](./licensing-and-entitlements.md) and
+[Billing](./billing.md).
+
+## Renaming
+
+The display name is free to change. The slug is the hostname and is not
+casually changed ask support if you need it.
+
+## What happens if the licence lapses
+
+A cloud instance whose Free licence expires enters degraded mode, then, after a
+grace period, the instance and all its data are deleted. Warning emails go out
+first. See [Free tier](./free-tier.md).
+
+Paid instances do not get reaped by that mechanism. A cancelled subscription
+runs to its grace-padded expiry and then lapses.
+
+## Deleting
+
+Ask support. Deletion is performed by the control plane, not by HQ the control
+plane is the only service that knows which collections carry the instance ID,
+and duplicating that list into HQ would be a list that drifts.

docsite/docs/hq/free-tier.md

@@ -0,0 +1,78 @@
+---
+id: free-tier
+title: Free tier
+sidebar_label: Free tier
+---
+
+Free is a real tier in both deployments not a trial that turns into nothing.
+
+## What you get
+
+|                       | Free      |
+| --------------------- | --------- |
+| Servers               | 3         |
+| Monitors              | 3         |
+| Secret groups         | 1         |
+| Notification channels | 1         |
+| Audit retention       | 30 days   |
+| Support               | Community |
+
+Browser console and single sign-on are not included; they are per-instance
+features on a paid plan.
+
+## One per account, per deployment
+
+The limit is enforced per account **and** deployment. A Free cloud instance does
+not prevent a Free self-hosted one they are separate slots.
+
+## Free is outside Paddle
+
+There is no subscription, no £0 line item and no invoice. Your account acquires
+a Paddle customer reference only with its first paid purchase.
+
+## Renewing
+
+Free licences have a term and must be renewed from the portal.
+
+- The renew button appears **7 days before expiry**.
+- It stays available **after** expiry, right up until the instance is reaped —
+  so the same button rescues a lapsed instance rather than needing a second
+  mechanism.
+- Renewing outside that window is refused, and the message names the date it
+  opens.
+
+:::tip Put the expiry in a calendar
+Warning emails go to the account address. If nobody watches that inbox, a Free
+cloud instance can lapse and eventually be deleted without anyone noticing.
+:::
+
+## What happens when it lapses
+
+**Self-hosted:** the instance goes into degraded mode after the grace period and
+stays that way. Nothing is deleted, ever.
+
+**Cloud:** the instance goes into degraded mode, and after a further period the
+instance **and all its data are deleted**. Warning emails are sent first, naming
+the date.
+
+:::danger Deletion is permanent
+There is no restore. If a cloud Free instance is approaching that date and you
+want to keep it, renew it, or move it to a paid plan.
+:::
+
+Deletion is carried out by the control plane rather than by HQ. HQ sends the
+warnings because it knows the billing address; the control plane performs the
+delete because it is the only service that knows which collections carry the
+instance ID.
+
+## Moving off Free
+
+Change the instance's configuration to a paid tier and check out. Your data
+stays where it is a tier change reissues a licence, it does not rebuild
+anything.
+
+## Relinks
+
+Free instances get the same relink allowance as paid ones: three per term. That
+cap exists to put a human in front of a fourth attempt, not to obstruct a
+genuine rebuild.

docsite/docs/hq/licensing-and-entitlements.md

@@ -0,0 +1,95 @@
+---
+id: licensing-and-entitlements
+title: Licensing and entitlements
+sidebar_label: Licensing and entitlements
+---
+
+A **licence** is a signed statement of what one instance may do. An
+**entitlement** is the configuration a licence is cut from.
+
+## Tiers
+
+Three tiers, in both deployments. The allowances are identical across cloud and
+self-hosted what differs is the term on offer, not what you get.
+
+|                       | Free      | Professional | Enterprise            |
+| --------------------- | --------- | ------------ | --------------------- |
+| Servers (base)        | 3         | 3            | 10                    |
+| Monitors              | 3         | unlimited    | unlimited             |
+| Secret groups         | 1         | unlimited    | unlimited             |
+| Notification channels | 1         | unlimited    | unlimited             |
+| Audit retention       | 30 days   | 365 days     | unlimited             |
+| Support               | Community | Email, 24×5  | Email and phone, 24×7 |
+
+The server count is **metered**: the base allowance comes with the tier, and you
+buy additional servers on top. That is why Professional shows a real number
+rather than "unlimited" the number you actually have is the one in your
+entitlement.
+
+## Features
+
+Two are per-instance toggles rather than tier bundles:
+
+| Feature   | What it enables                                                           |
+| --------- | ------------------------------------------------------------------------- |
+| `console` | The [browser console](../vantage/browser-console.md)                      |
+| `oidc`    | Per-instance [single sign-on](../vantage/settings.md#single-sign-on-oidc) |
+
+No tier includes them by default; you enable them on the instances that need
+them.
+
+## Entitlements: desired and granted
+
+Each instance has one entitlement row holding two configurations:
+
+|             | Meaning                      |
+| ----------- | ---------------------------- |
+| **Desired** | What you last asked for      |
+| **Granted** | What a payment has confirmed |
+
+Checkout is built from **desired**. A licence is only ever signed from
+**granted**. An abandoned checkout therefore leaves a desired that reached
+nothing and changed nothing.
+
+### Increases and reductions
+
+An increase takes effect when payment confirms, and the entitlement is promoted
+desired → granted.
+
+A **reduction** is scheduled rather than immediate: you keep what you paid for
+until the end of the term, and the portal shows the date it drops. The collapse
+happens at renewal.
+
+## What a licence carries
+
+Instance UUID, deployment, tier, resolved limits, features, term and expiry —
+all signed.
+
+Two properties follow from that:
+
+- **A licence is bound to one instance UUID.** Moving it takes a
+  [relink](./self-hosted-instances.md#relinking).
+- **A licence is a snapshot.** Editing a plan later never rewrites an issued
+  licence, the same way editing a workflow step never rewrites a past run.
+
+Verification is local. Your instance does not call HQ to check a licence, and
+signing happens only in HQ.
+
+## Expiry and grace
+
+Expiry is padded with a grace period. Past that, the instance goes into degraded
+mode: it keeps running and keeps your data, but stops letting you do everything.
+
+The way out is a current licence renew or purchase, then paste it (self-hosted)
+or let it be written for you (cloud).
+
+## Server limits in practice
+
+When you exceed your server allowance, enrolling another one is refused. The
+existing fleet is unaffected. Raise the allowance in the portal, or remove a
+server you are not using.
+
+## Legacy tiers
+
+An older `self_hosted` tier is mapped forward to self-hosted Professional
+wherever it appears. Nothing needs doing about it.

docsite/docs/hq/people-and-roles.md

@@ -0,0 +1,98 @@
+---
+id: people-and-roles
+title: People and roles
+sidebar_label: People and roles
+---
+
+Two separate things live here: who is in your **account**, and who has access to
+each **instance**.
+
+## Account members
+
+**People** lists everyone in the account.
+
+| Role     | Can                                             |
+| -------- | ----------------------------------------------- |
+| `owner`  | Everything, including billing                   |
+| `admin`  | Invite, create instances, grant instance access |
+| `member` | Read                                            |
+
+Owners and admins invite; billing is owner-only.
+
+### Inviting someone
+
+1. **People → Invite**.
+2. Enter their email and pick a role.
+3. They receive a link and set their own password at `/accept-invite`.
+
+:::info Why you cannot set their password
+An invitation creates a person with an **empty password hash**, which cannot
+authenticate at all until they set one. If the inviter chose it, that password
+would be a shared credential to every instance the person is later granted
+access to.
+
+The verification endpoint knows the difference: a token belonging to a
+passwordless person reports that a password is needed and is left unspent, so
+the link still works when they get to it.
+:::
+
+### Removing someone
+
+Removing them from the account removes their portal access. See below for what
+happens to their instance access.
+
+## Instance access
+
+Granting access to a **cloud** instance creates a real user inside that
+instance's control plane, with `auth_source: "hq"`.
+
+```mermaid
+flowchart LR
+    P["HQ account member"] -->|grant| U["Control-plane user<br/>auth_source: hq"]
+    U --> I["The instance authenticates<br/>this user like any other"]
+```
+
+The instance authenticates that user exactly as it authenticates anyone else,
+with **no runtime dependency on HQ**. Revoking deletes the row the control
+plane has no disabled state, and a row that exists is a row that can sign in.
+
+### Granting
+
+On an instance record, **Members → Add**, choose an account member and an
+instance role (`owner`, `admin`, `member`).
+
+One person holds at most one user per instance, so granting twice is refused
+rather than quietly creating a second user.
+
+### Roles inside an instance
+
+Independent of the account role. Someone can be an account `member` and an
+instance `owner`, or the reverse.
+
+### Revoking
+
+Removes the user from the instance immediately. Any live session ends with the
+session, since the user row backing it is gone.
+
+:::warning Self-hosted instances cannot be granted from HQ
+All three member endpoints refuse when the instance is self-hosted. Manage those
+users in the instance itself, at **Settings → Access**.
+:::
+
+## Passwords
+
+Your HQ password is the single source of truth for every user projected from it.
+Changing it in the portal rehashes it and copies the hash to every instance you
+have been granted.
+
+Propagation is best-effort and immediate; a background pass compares and repairs
+every 15 minutes, so a temporarily unreachable instance catches up on its own.
+
+There is no local password-change endpoint for those users in the control plane,
+so there is never a second writer for the hash.
+
+:::warning HQ-managed users are read-only in the instance
+Changing the role of, or deleting, an `hq`-sourced user inside the control plane
+is refused with `409`. Do it from the portal. The UI shows those rows read-only
+with a link back here, but the API is the boundary; the UI is the courtesy.
+:::

docsite/docs/hq/self-hosted-instances.md

@@ -0,0 +1,74 @@
+---
+id: self-hosted-instances
+title: Self-hosted instances
+sidebar_label: Self-hosted instances
+---
+
+A self-hosted instance is your install, licensed through HQ. HQ never touches
+it: it issues a signed file that your install verifies locally.
+
+## Free
+
+Install first, then link and claim. Step by step in
+[Claim a Free licence](../getting-started/claim-free-licence.md).
+
+## Paid
+
+Buying happens **before** the install has to exist, because you may well be
+buying in order to build it.
+
+```mermaid
+flowchart LR
+    A["Buy in HQ"] --> B["Placeholder instance<br/>awaiting_link, no licence"]
+    B --> C["Install Vantage<br/>get its instance UUID"]
+    C --> D["Paste the UUID<br/>claim-link"]
+    D --> E["Licence issued<br/>bound to that UUID"]
+```
+
+1. **Overview → Buy self-hosted**, choose tier, term and configuration.
+2. Complete checkout. HQ creates a **placeholder** instance in state
+   `awaiting_link` with no licence attached.
+3. [Install Vantage](../getting-started/self-hosted-install.md) if you have not
+   already, and find its instance UUID at **Settings → Licence**.
+4. Back in HQ, open the placeholder and paste the UUID.
+5. The licence is issued, bound to that UUID. Download it and paste it into your
+   install.
+
+:::info Why there is a placeholder at all
+A licence binds to an instance UUID, and at the moment of payment that UUID may
+not exist yet. Issuing early would mean issuing to nothing; refusing to sell
+until you had installed would be the wrong order. The placeholder holds the
+purchase until there is something to bind to.
+:::
+
+## Linking an existing install
+
+If the install already exists, **Link an instance** takes the UUID directly. A
+UUID already claimed by another account is refused with a conflict.
+
+## Relinking
+
+Rebuilding the host produces a new instance UUID, and the old licence no longer
+matches. **Relink** moves the licence to the new UUID and reissues.
+
+The number of relinks per term is capped, and the portal shows how many you have
+left. This is not meant to obstruct disaster recovery if you have exhausted
+them for a real reason, ask support.
+
+## Installing the licence
+
+Paste it at **Settings → Licence** in your install. The instance verifies the
+signature and checks that the UUID matches its own.
+
+Pasting works even while the current licence is expired that endpoint is
+exempt from the licence check, because it is the route out of degraded mode.
+
+## Keeping it current
+
+Your install does not fetch licences. When a licence is reissued renewal,
+configuration change, relink download the new one from HQ and paste it in.
+
+:::warning Nothing reminds your install
+The control plane knows only what its licence says. Expiry emails come from HQ,
+to the account's address. Make sure someone reads them.
+:::

docsite/docs/index.md

@@ -0,0 +1,37 @@
+---
+id: index
+title: Vantage documentation
+sidebar_label: Overview
+slug: /
+---
+
+# Vantage documentation
+
+Vantage is a self-hosted, multi-tenant infrastructure control plane. It manages
+SSH keys, runs scripted workflows, watches services, stores secrets, opens
+browser consoles and applies OS updates across a fleet of servers.
+
+A central server drives a lightweight agent installed on each managed machine.
+The agent connects **outbound only**, so managed servers need no inbound
+firewall holes.
+
+## Where to start
+
+| If you want to                          | Read                                                            |
+| --------------------------------------- | --------------------------------------------------------------- |
+| Understand what the pieces are          | [What is Vantage](./getting-started/what-is-vantage.md)         |
+| Run it on your own hardware             | [Self-hosted install](./getting-started/self-hosted-install.md) |
+| Enrol your first machine                | [Add your first server](./getting-started/first-server.md)      |
+| Manage your account, licence or billing | [Vantage HQ](./hq/accounts-and-signup.md)                       |
+| Look something up                       | [Reference](./reference/environment-variables.md)               |
+
+## The two products
+
+**Vantage** is the control plane the thing you sign in to in order to manage
+servers. It runs either on your own infrastructure or as a cloud instance we
+run for you.
+
+**Vantage HQ** is the portal at `vantage-hq.hostxtra.co.uk` where you manage the
+account behind those instances: who is on your team, which instances exist, what
+licence each one holds and how it is billed. HQ never manages your servers, and
+a Vantage instance never depends on HQ being reachable in order to run.

docsite/docs/operations/agent-updates.md

@@ -0,0 +1,77 @@
+---
+id: agent-updates
+title: Agent updates
+sidebar_label: Agent updates
+---
+
+Agents are versioned and released independently of the control plane, and update
+themselves on command.
+
+## Checking the current version
+
+Each server's detail page shows the version it reported at its last sync.
+`GET /api/agent/latest-version` reports the newest release available.
+
+## Updating from the UI
+
+**Servers → _a server_ → Update agent** pushes `UpdateAgentCmd` with a target
+version. The agent then:
+
+1. Downloads the binary for its platform from the release.
+2. Verifies the SHA-256 against `checksums.txt`.
+3. Stops itself, replaces the binary in place, and starts again.
+
+`Restart=always` on the systemd unit is what makes the last step work.
+
+The server briefly goes `offline` and comes back within a poll interval or two.
+
+## Updating from the machine
+
+There is a dynamic update script, the counterpart to the install one:
+
+```bash
+curl -fsSL https://vantage.example.com/update | bash
+```
+
+```powershell
+irm https://vantage.example.com/update.ps1 | iex
+```
+
+It does the same download, checksum and replace, then restarts the service. Use
+this when the control plane cannot push for example, when the machine is
+reachable but its command stream is not.
+
+## Rolling out across a fleet
+
+There is no built-in bulk update. Two reasonable approaches:
+
+- Update from each server's page, a few at a time.
+- Build a [workflow](../vantage/workflows.md) whose step runs the update script,
+  and target it at the machines you want. That gives you ordering, failure
+  handling and a log.
+
+:::tip Update a canary first
+An agent that fails to start after replacing itself needs hands on that machine.
+Do one, confirm it returns to `active`, then do the rest.
+:::
+
+## Version compatibility
+
+The agent API is versioned to tolerate an agent older than the control plane. The
+reverse an agent newer than the control plane is not a case anyone tests.
+Upgrade the control plane first.
+
+Agents report their version on every poll, so a fleet running mixed
+versions is visible in the server list rather than something you have to go
+looking for.
+
+## If an update fails
+
+| Symptom                           | Cause                                                                                                                               |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| "Checksum mismatch"               | Interrupted download, or a proxy rewriting the body. Retry                                                                          |
+| Downloads nothing                 | The machine cannot reach `gitea.hostxtra.co.uk`                                                                                     |
+| Service will not start afterwards | Wrong architecture binary, or the file was replaced while a different service manager held it. Reinstall with the install one-liner |
+
+Reinstalling is always safe: the config file is left alone, so the agent comes
+back with the same identity and token.

docsite/docs/operations/backups.md

@@ -0,0 +1,89 @@
+---
+id: backups
+title: Backups
+sidebar_label: Backups
+---
+
+Two things matter: **MongoDB** and **`KEY_ENCRYPTION_KEY`**. A backup missing
+either one restores to something unusable.
+
+## What holds what
+
+| Store                | Contents                                                                                                      | Back up                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| MongoDB              | Everything durable servers, keys, assignments, workflows, runs, monitors, incidents, secrets, settings, audit | **Yes**                                           |
+| Redis                | Sessions only                                                                                                 | No. Losing it signs everyone out and nothing else |
+| `./data` bind mount  | Workflow run logs                                                                                             | Optional                                          |
+| `KEY_ENCRYPTION_KEY` | Not stored anywhere by the app                                                                                | **Yes, separately**                               |
+
+:::danger The database alone is not a backup
+Private keys, vault secrets, OIDC client secrets and console credentials are
+encrypted with `KEY_ENCRYPTION_KEY`, which lives in your environment file and
+nowhere in the database. Restore the database without it and every one of those
+values is permanently unreadable.
+
+Store the key somewhere other than the server it protects.
+:::
+
+## Backing up MongoDB
+
+With the bundled Mongo container:
+
+```bash
+docker compose exec -T mongo mongodump --archive --gzip --db vantage \
+  > /backups/vantage-$(date +%F).archive.gz
+```
+
+Restoring:
+
+```bash
+docker compose exec -T mongo mongorestore --archive --gzip --drop \
+  < /backups/vantage-2026-07-28.archive.gz
+```
+
+`--drop` replaces existing collections. Stop the `server` container first, so
+nothing writes during the restore.
+
+## Backing up the environment file
+
+```bash
+cp /opt/vantage/.env /secure-location/vantage.env
+```
+
+Treat it as a credential in its own right it holds the encryption key.
+
+## Run logs
+
+Workflow run logs live in the `./data` bind mount, not in the database. They are
+swept on the retention schedule anyway, so most people do not back them up. If
+you keep them for compliance, set retention to `0` (forever) and include the
+directory.
+
+## What a restore gives you
+
+Everything: fleet, keys, assignments, workflows and their history, monitors and
+incidents, secrets, settings and the audit log.
+
+What it does **not** do is reconcile the world. After a restore:
+
+- Agents reconnect with their existing tokens, since the token hashes are in the
+  database.
+- If the restore is older than an enrolment, that server's token hash is missing
+  and the agent will fail to authenticate re-enrol it.
+- The next agent poll rewrites `authorized_keys` to match the restored desired
+  state, which may remove keys added since the backup.
+
+## A workable schedule
+
+| What              | When                                                  |
+| ----------------- | ----------------------------------------------------- |
+| MongoDB dump      | Nightly, retained per your policy                     |
+| Environment file  | On change, held in a password manager or secret store |
+| Restore rehearsal | Occasionally, into a throwaway host                   |
+
+The rehearsal is the part that gets skipped and the part that finds the
+problems.
+
+## Cloud instances
+
+We back these up. You do not need to.

docsite/docs/operations/upgrading.md

@@ -0,0 +1,71 @@
+---
+id: upgrading
+title: Upgrading
+sidebar_label: Upgrading
+---
+
+Upgrading the control plane is a pull and a recreate. Agents are versioned and
+upgraded separately see [Agent updates](./agent-updates.md).
+
+:::info Cloud instances upgrade themselves
+This page is for self-hosted installs. If your instance is hosted by us, there
+is nothing here for you to do.
+:::
+
+## Upgrade
+
+```bash
+cd /opt/vantage
+docker compose pull
+docker compose up -d --remove-orphans
+```
+
+`--remove-orphans` clears containers for services that no longer exist in the
+Compose file, which is what leaves a stale container running after a service is
+renamed or removed.
+
+## What happens on boot
+
+1. **Migrations** run, recording markers so each runs once.
+2. **Indexes** are ensured. Auth and settings index builders are fatal on
+   failure; secret and workflow ones only warn.
+3. **Default steps** are reseeded from the image, overwriting the `default`
+   library which is why those steps are read-only.
+
+Watch it:
+
+```bash
+docker compose logs -f server
+```
+
+## Before you upgrade
+
+- **Back up MongoDB.** See [Backups](./backups.md). Migrations are one-way.
+- **Read the release notes** for anything about migrations or environment
+  variables.
+- **Check your `.env`** still supplies everything required. A newly required
+  variable stops the boot rather than defaulting to something unsafe.
+
+## Downgrading
+
+There is no automatic downgrade. Migrations do not roll back, so returning to an
+older image means restoring the database backup taken before the upgrade. This
+is the reason the backup is not optional.
+
+## Zero-downtime
+
+The stack is not designed for it. `docker compose up -d` recreates the server
+container, which is a short interruption:
+
+- Agents reconnect on their own they retry, and the poll loop is idempotent.
+- Workflow runs in progress lose their command stream. Steps already dispatched
+  finish on the agent, but their results have nowhere to go. **Do not upgrade
+  during a run.**
+- Sessions survive, because they live in Redis rather than in the server.
+
+## After upgrading
+
+- Confirm every service is `running`.
+- Confirm servers return to `active` within a couple of poll intervals.
+- Open a page that touches encryption a secret group to confirm
+  `KEY_ENCRYPTION_KEY` came through.

docsite/docs/reference/agent-config.md

@@ -0,0 +1,111 @@
+---
+id: agent-config
+title: Agent configuration
+sidebar_label: Agent config
+---
+
+The agent reads no environment variables. Everything is in one YAML file.
+
+## Location
+
+| Platform | Path                                |
+| -------- | ----------------------------------- |
+| Linux    | `/etc/vantage/config.yaml`          |
+| Windows  | `%ProgramData%\vantage\config.yaml` |
+
+Directory `0700`, file `0600`. The install script sets both.
+
+## Contents
+
+```yaml
+server_url: "vantage.yourdomain.com:9090"
+server_id: "<uuid>"
+pre_reg_token: "<token>" # removed after the first successful Register()
+agent_token: "" # written by the agent after Register()
+poll_interval: 30s
+tls: true
+```
+
+| Field           | Meaning                                                               |
+| --------------- | --------------------------------------------------------------------- |
+| `server_url`    | `host:port` of the gRPC endpoint. Comes from the server's `GRPC_HOST` |
+| `server_id`     | The identity issued when the enrolment was created                    |
+| `pre_reg_token` | Single-use, one hour. Cleared once registration succeeds              |
+| `agent_token`   | The permanent credential, written by the agent itself                 |
+| `poll_interval` | How often the agent polls for key state. Default `30s`                |
+| `tls`           | Whether to use TLS. Leave `true`                                      |
+
+:::danger This file is the credential
+`agent_token` is plaintext here and nowhere else the control plane holds only
+its SHA-256. Anyone who can read this file can act as this agent. That is why
+it is `0600` and the directory is `0700`.
+:::
+
+## Startup sequence
+
+```
+1. Load the config
+2. pre_reg_token present → register → save agent_token,
+   clear pre_reg_token, reconnect
+3. Start: command stream · hourly update check · inventory · monitors
+4. Enter the key poll loop
+```
+
+## The poll loop
+
+```
+1. Ask the control plane for the desired key state, reporting the
+   agent version
+2. Non-Linux hosts stop here Windows agents register and heartbeat only
+3. Diff the desired keys against /root/.ssh/authorized_keys;
+   unchanged → write nothing
+4. Changed → write a temp file, rename it over the real one, chmod 0600
+```
+
+## Service management
+
+### Linux
+
+Unit at `/etc/systemd/system/vantage-agent.service`, `Restart=always`, running
+as root.
+
+```bash
+systemctl status vantage-agent
+systemctl restart vantage-agent
+journalctl -u vantage-agent -f
+```
+
+### Windows
+
+A service registered through NSSM, or installed by the MSI that CI builds.
+
+```powershell
+Get-Service vantage-agent
+Restart-Service vantage-agent
+```
+
+## Command-line flags
+
+```
+vantage-agent -generate-key
+```
+
+Generates a keypair locally. Normal operation takes no flags.
+
+## Moving an agent to a new control plane
+
+Change `server_url`, clear `agent_token`, set a fresh `pre_reg_token` from a new
+enrolment, and restart. The old control plane still holds a server record that
+will go `offline`; delete it there.
+
+## Uninstalling
+
+```bash
+systemctl disable --now vantage-agent
+rm -f /usr/local/bin/vantage-agent /etc/systemd/system/vantage-agent.service
+rm -rf /etc/vantage
+systemctl daemon-reload
+```
+
+Keys already written to `authorized_keys` remain on disk the agent is no
+longer running to remove them. Revoke first if that matters.

docsite/docs/reference/environment-variables.md

@@ -0,0 +1,47 @@
+---
+id: environment-variables
+title: Environment variables
+sidebar_label: Environment variables
+---
+
+Everything the control plane reads from the environment, and what happens when
+it is absent.
+
+## Server
+
+| Name                       | Required        | Default                     | Notes                                                                                                                                                              |
+| -------------------------- | --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GRPC_HOST`                | **yes**         |                             | The `host:port` agents dial. Boot fails without it. There is deliberately no fallback to the web host: that would hand every agent a port that does not speak gRPC |
+| `MONGO_URI`                | no              | `mongodb://localhost:27017` | The database name is taken from the URI path, falling back to `vantage`. There is no separate `MONGO_DB`                                                           |
+| `REDIS_ADDR`               | no              | `localhost:6379`            | Sessions, and the bus that routes agent commands between server replicas. Every replica must point at the **same** Redis                                            |
+| `REDIS_USERNAME`           | no              |                             | Redis 6+ ACL user. Leave empty against a legacy `requirepass` instance, which authenticates with the password alone                                                |
+| `REDIS_PASSWORD`           | no              |                             | Leave empty for an unauthenticated Redis. Both of these exist so an install can use a managed Redis rather than the bundled one                                    |
+| `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                                                                     |
+| `POD_IP`                   | no              |                             | Kubernetes only, set by the Helm chart from the downward API. Overrides `PROXY_ADVERTISE_HOST`, because a console relay belongs to one replica and a Service address names all of them |
+| `APP_ROOT_LABEL`           | no              | `vantage`                   | The app root label for the host and session organisation guard                                                                                                     |
+
+:::danger `KEY_ENCRYPTION_KEY` has no recovery path
+It encrypts SSH private keys, vault secrets, OIDC client secrets and console
+credentials. Lose it and all of them are unreadable. Back it up separately from
+the database it protects.
+:::
+
+:::info A wrong `APP_ROOT_LABEL` fails quietly
+It does not error. It simply stops matching, and the host/session guard stops
+protecting anything.
+:::
+
+### Not configurable
+
+The HTTP port (`8080`) and the gRPC port (`9090`) are fixed in the server. The
+`HTTP_PORT` and `GRPC_PORT` entries in the shipped Compose file are inert —
+remap with Docker's port publishing instead.
+
+## Agent
+
+The agent reads no environment variables. Everything is in its
+[config file](./agent-config.md).

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

@@ -0,0 +1,92 @@
+---
+id: ports-and-networking
+title: Ports and networking
+sidebar_label: Ports and networking
+---
+
+## Control plane ports
+
+| Port    | Service     | Who connects                     | Expose publicly |
+| ------- | ----------- | -------------------------------- | --------------- |
+| `3000`  | web         | Browsers, via your reverse proxy | Yes, behind TLS |
+| `8080`  | server REST | The web app                      | No              |
+| `9090`  | server gRPC | Agents                           | **Yes**         |
+| `4822`  | guacd       | The server                       | No              |
+| `27017` | MongoDB     | The server                       | No              |
+| `6379`  | Redis       | The server                       | No              |
+
+## Direction of travel
+
+```mermaid
+flowchart LR
+    B["Browser"] -->|HTTPS| P["Reverse proxy"]
+    P --> W["web :3000"]
+    W --> S["server :8080"]
+    A["Agent on a managed server"] -->|"gRPC/TLS :9090, outbound"| S
+    S --> G["guacd :4822"]
+    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.
+
+**Agents connect outbound.** No inbound rule is needed on a managed server, and
+NAT is not an obstacle. The only requirement is that the machine can reach
+`GRPC_HOST`.
+
+**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
+
+### On your firewall, inbound to the control plane
+
+- Your web port, from wherever people are.
+- `9090`, from every network holding managed machines.
+
+### Outbound from the control plane
+
+- `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.
+
+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
+
+- `GRPC_HOST`.
+- `gitea.hostxtra.co.uk`, for install and self-update.
+- Its package mirrors, for OS updates.
+
+## TLS
+
+Terminate TLS for the web UI at your reverse proxy.
+
+gRPC on `9090` is reached directly by agents with `tls: true`, so that port needs
+a valid certificate for the name in `GRPC_HOST`. If you proxy it, the proxy must
+speak HTTP/2 end to end many do not by default, and the symptom is agents that
+register and then fail to hold the command stream.
+
+## Reverse proxy notes
+
+- Point the proxy at `web:3000`. The web app reaches the REST API internally, so
+  `8080` does not need publishing.
+- The console uses a **WebSocket** at `/api/console/tunnel`. A proxy that does
+  not forward upgrade headers breaks the console and nothing else.
+- Workflow log streaming is a long-lived response. A short proxy read timeout
+  truncates live logs while the run itself continues.
+
+## Air-gapped and restricted networks
+
+The control plane needs outbound access to fetch agent releases. Managed
+machines need it too, unless you distribute the agent binary yourself and write
+the config by hand the install script's only job is to do those two things.
+
+Licence verification is entirely local, so a licensed install works with no
+outbound access to HQ at all.

docsite/docs/reference/rest-api.md

@@ -0,0 +1,149 @@
+---
+id: rest-api
+title: REST API
+sidebar_label: REST API
+---
+
+The control plane's HTTP API, on port `8080`. The web UI is a client of it and
+has no privileges it does not.
+
+## Authentication
+
+Most endpoints take a session: an opaque 32-byte token in the `km_session`
+cookie, with the body in Redis for 24 hours.
+
+One endpoint takes a bearer token instead the External Secrets Operator read
+path.
+
+## Unauthenticated
+
+```
+GET  /install            /install.ps1        # dynamic agent install scripts
+GET  /update             /update.ps1
+GET  /auth/bootstrap-status
+POST /auth/bootstrap     /auth/login  /auth/logout
+GET  /auth/me            /auth/oidc/start    /auth/oidc/callback
+GET  /api/secrets/:group/values               # bearer token (ESO)
+```
+
+`/install` and `/install.ps1` take `server_id` and `token` as query parameters
+and return a shell script with the newest agent version substituted in.
+
+`POST /auth/bootstrap` works only while the database has no users.
+
+## Session-authenticated, under `/api`
+
+### Servers
+
+```
+GET,POST   /servers
+GET,POST   /servers/new
+GET,DELETE /servers/:id
+POST       /servers/:id/generate-key
+POST       /servers/:id/update-agent
+POST       /servers/:id/apply-updates
+```
+
+### Keys
+
+```
+GET,POST   /keys
+GET,DELETE /keys/:id
+GET        /keys/:id/private-key
+POST       /keys/:id/assign
+DELETE     /keys/:id/assign/:serverId
+```
+
+### Workflows and steps
+
+```
+GET,POST       /steps
+PUT,DELETE     /steps/:id
+GET            /steps/:id/export
+POST           /steps/import · /steps/seed-defaults · /steps/parse
+GET            /steps/usage
+GET,POST       /workflows
+GET,PUT,DELETE /workflows/:id
+POST           /workflows/:id/run
+GET            /workflows/:id/runs
+GET            /runs/:runId
+POST           /runs/:runId/cancel
+GET            /runs/:runId/servers/:serverId/logs
+GET            /runs/:runId/servers/:serverId/logs/stream
+```
+
+`PUT` and `DELETE` on a step whose source is `default` answer `409`. See
+[Workflows](../vantage/workflows.md#default-steps).
+
+### Monitors and channels
+
+```
+GET,POST       /monitors
+GET,PUT,DELETE /monitors/:id
+GET            /monitors/:id/incidents · /monitors/:id/uptime
+GET,POST       /channels
+PUT,DELETE     /channels/:id
+POST           /channels/:id/test
+```
+
+### Secrets
+
+```
+GET,POST       /secrets
+GET,PUT,DELETE /secrets/:group
+POST           /secrets/:group/reveal
+DELETE         /secrets/:group/:key
+```
+
+### Console
+
+```
+POST /console/connect
+GET  /console/tunnel        # websocket
+```
+
+### Other
+
+```
+GET  /audit
+GET  /agent/latest-version
+GET,PUT /settings                            (owner|admin)
+POST /settings/secrets-token                 (owner|admin)
+GET  /license
+POST /license                                (self-hosted only)
+GET,POST   /org/users
+PUT        /org/users/:id/role
+DELETE     /org/users/:id
+GET,PUT    /org/oidc                         (owner|admin)
+```
+
+## Notable refusals
+
+| Endpoint                                           | Condition                      | Status              |
+| -------------------------------------------------- | ------------------------------ | ------------------- |
+| `POST /license`                                    | deployment is `cloud`          | `409 cloud_managed` |
+| `PUT,DELETE /steps/:id`                            | the step's source is `default` | `409`               |
+| `PUT /org/users/:id/role`, `DELETE /org/users/:id` | the user's auth source is `hq` | `409`               |
+
+`POST /license` is exempt from the licence check, so pasting a valid licence
+works while the current one is expired that is the way out of degraded mode.
+
+## Multi-tenancy
+
+Every request is scoped to the instance resolved from the session. On a
+multi-tenant deployment, a request arriving at `<slug>.vantage.<tld>` also has
+its host checked against the session's instance, and a mismatch is rejected.
+
+## Errors
+
+Errors are JSON with an `error` field. Customer-facing endpoints in the HQ API
+answer `404` rather than `403` for another account's resource, because a `403`
+confirms the resource exists; the control plane's own API is single-tenant per
+session and does not need that distinction.
+
+## Admin API
+
+Vantage HQ is a separate hosted service with its own API and its own session.
+Its behaviour is described in the [Vantage HQ](../hq/accounts-and-signup.md)
+section rather than here; the two services share no session and no
+authentication.

docsite/docs/reference/troubleshooting.md

@@ -0,0 +1,133 @@
+---
+id: troubleshooting
+title: Troubleshooting
+sidebar_label: Troubleshooting
+---
+
+Symptoms, in the order people hit them.
+
+## The server will not start
+
+**Exits immediately on boot.** Almost always a missing `GRPC_HOST` the server
+refuses to start rather than guess a value that would break every agent later.
+
+**Fails during index creation.** The auth and settings index builders are fatal
+on failure by design: those unique indexes are what enforce tenant isolation,
+so starting without them is worse than not starting. Check the MongoDB user's
+permissions and whether a conflicting index already exists.
+
+**Starts, but every secret operation errors.** `KEY_ENCRYPTION_KEY` is missing
+or is not 64 hex characters.
+
+## Nobody can sign in
+
+**`/setup` appears when users already exist.** The server is pointed at a
+different database than you think. Check the database name in `MONGO_URI` —
+it comes from the URI path, not a separate variable.
+
+**Sessions do not stick.** Redis is unreachable, or the cookie is being dropped
+because the site is served over plain HTTP.
+
+**"Wrong organisation" style rejections.** The host and session guard is
+comparing the request host's label against the session's organisation. Check
+`APP_ROOT_LABEL`.
+
+**OIDC redirects and then fails.** The callback URL registered with the provider
+must match exactly. Keep one local owner account so a broken provider is not a
+lockout.
+
+## A server never becomes active
+
+Work through it in this order:
+
+1. Is the agent running? `systemctl status vantage-agent`.
+2. What does it say? `journalctl -u vantage-agent -f`.
+3. Can that machine reach the endpoint? Test `GRPC_HOST` **from the machine**,
+   not from the control plane host.
+4. Was the token already used or expired? It is single-use and lives one hour —
+   create a fresh enrolment rather than reusing the old command.
+
+| Symptom                                       | Cause                                                                                                                  |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Registers, then goes `offline` within minutes | Something permits the short `Register` call but drops the long-lived stream. Usually a proxy or idle-timeout middlebox |
+| Stays `pending` forever                       | Registration never happened. Token spent, or the endpoint unreachable                                                  |
+| Flaps between `active` and `offline`          | Intermittent path, or a poll interval longer than the offline threshold                                                |
+
+Remember the offline sweep runs every two minutes, so status is never
+instantaneous.
+
+## Keys are not appearing on a machine
+
+- **It is a Windows server.** Key management is Linux-only, by design.
+- **The agent is not running.** Nothing polls, nothing writes.
+- **The key is assigned but revoked.** Revocation is soft; check the assignment
+  state rather than the key.
+- **Someone edited `authorized_keys` by hand.** The agent rewrites the file to
+  match the desired set; hand-added keys disappear on the next change.
+
+## A workflow run fails or hangs
+
+- **Hangs at dispatch.** The target's command stream is not connected the
+  server may be `offline`.
+- **Fails immediately with an interpreter error.** A bash step on a Windows
+  target, or PowerShell on Linux.
+- **A value does not reach the next step.** Values pass through the file at
+  `$WORKFLOW_ENV`, one `KEY=value` per line. Declaring an output does not export
+  it.
+- **A secret is empty.** The group is not in the step's `secret_refs`, or the
+  key name differs from the environment variable you are reading.
+- **Logs stop mid-run.** A reverse proxy read timeout cut the stream. The run
+  itself continues; reload the page.
+
+## The console will not connect
+
+| Symptom                       | Cause                                                                                                           |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| 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, 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
+
+- The check is running from the control plane and the endpoint is only reachable
+  internally. Switch the runner to an agent on a machine that can see it.
+- The keyword no longer appears in the response body.
+- Retries are `0`, so a single dropped packet flips the state.
+
+## Notifications are not arriving
+
+Use the channel **Test** button it goes through the real delivery path, so a
+test that arrives proves credentials, network path and destination.
+
+If the test fails: a webhook returning 300 or above counts as a failure, SMTP
+needs `host`, `port`, `from` and `to`, and Telegram needs both `token` and
+`chat_id`.
+
+## Licence problems
+
+| Symptom                                           | Cause                                                                                                          |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `409 cloud_managed` when pasting                  | It is a cloud instance. Licences are written by HQ; there is nothing to paste                                  |
+| Licence rejected as not matching                  | It is bound to a different instance UUID. Relink in HQ                                                         |
+| Instance degraded despite a valid-looking licence | It has expired past its grace period. Pasting still works that endpoint stays available specifically so it can |
+| Cannot enrol another server                       | The server allowance is reached. Raise it in HQ or remove one                                                  |
+
+## HQ portal problems
+
+The portal is a hosted service, so problems with it are ours to fix rather than
+yours to configure. If a page fails to load, an action reports an error, or a
+plan or price looks wrong after a change, contact support with your instance
+UUID and roughly when it happened.
+
+## Gathering information before asking for help
+
+```bash
+docker compose ps
+docker compose logs --tail=200 server
+journalctl -u vantage-agent --no-pager -n 200   # on the affected machine
+```
+
+Include your instance UUID from **Settings → Licence** it is the reference
+support works from.

docsite/docs/vantage/audit-log.md

@@ -0,0 +1,51 @@
+---
+id: audit-log
+title: Audit log
+sidebar_label: Audit log
+---
+
+Every mutating API path writes an audit event. The log is at **Audit**.
+
+## What an event carries
+
+| Field  | Meaning                                                  |
+| ------ | -------------------------------------------------------- |
+| Action | A dotted name, e.g. `server.created`, `settings.updated` |
+| Actor  | Who did it                                               |
+| Target | The object acted on                                      |
+| Detail | A short human-readable note                              |
+| Time   | When                                                     |
+
+## What is recorded
+
+Creation, modification and deletion across the product: servers and enrolments,
+keys and assignments, workflow and step changes, runs triggered, monitors and
+channels, secret groups and reveals, console sessions opened, settings and
+member changes, licence installs.
+
+Reads are not recorded, with one deliberate exception: **revealing a secret**
+writes an event, because reading that particular thing is an act rather than a
+lookup.
+
+## What is not recorded
+
+- Sign-ins and sign-out.
+- Anything inside a console session.
+- Step output. That lives in the run log, kept under the workflow retention
+  setting rather than with the audit log.
+
+## Retention
+
+Audit events are not swept by the workflow log retention setting that setting
+governs run logs only. Audit history stays until the instance does.
+
+:::warning It is a log, not a control
+The audit log tells you what happened. It does not restrict what can happen, and
+an admin can do anything an admin can do. Use roles for restriction and the log
+for accountability.
+:::
+
+## Getting events out
+
+`GET /api/audit` returns recent events as JSON and accepts a `limit`. There is
+no streaming or push export; if you need events in a SIEM, poll that endpoint.

docsite/docs/vantage/browser-console.md

@@ -0,0 +1,73 @@
+---
+id: browser-console
+title: Browser console
+sidebar_label: Browser console
+---
+
+An SSH, RDP or VNC session in a browser tab, with no client software and no
+inbound port on the target beyond the one the protocol already uses.
+
+Protocol handling is Apache Guacamole's the control plane proxies a WebSocket
+to a **guacd** daemon and manages credentials around it.
+
+## Requirements
+
+- `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.
+- 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. 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.
+
+## Credentials
+
+### SSH
+
+Authenticates with a private key stored in the [key library](./ssh-keys.md). The
+key must have its private half uploaded; a public-only key cannot open a
+session.
+
+### RDP and VNC
+
+You supply credentials when connecting. They are encrypted, **single-use**, and
+consumed when the tunnel opens. They are not retained for the next session.
+
+:::info Why single-use
+A stored console credential is a standing grant to that machine for anyone who
+can reach the endpoint. Consuming it at tunnel-open means a leaked session token
+is worth one connection at most, and only until it is used.
+:::
+
+## Session behaviour
+
+Closing the tab ends the session. There is no reconnect and no session
+persistence reopening mints a new token and a new connection.
+
+## Auditing
+
+Opening a console is an audited action, with actor, server and time. What
+happens _inside_ the session is not recorded: there is no session capture or
+keystroke log. If you need that, it has to come from the target machine.
+
+## When it does not work
+
+| Symptom                          | Cause                                                                           |
+| -------------------------------- | ------------------------------------------------------------------------------- |
+| 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, 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 |

docsite/docs/vantage/monitors.md

@@ -0,0 +1,78 @@
+---
+id: monitors
+title: Monitors
+sidebar_label: Monitors
+---
+
+Monitors check that something is answering. Four types, two places they can run
+from, and a notification path when they stop being satisfied.
+
+## Types
+
+| Type   | Checks                                  | Options                                                                           |
+| ------ | --------------------------------------- | --------------------------------------------------------------------------------- |
+| `http` | An HTTP(S) URL                          | method, expected status, keyword that must appear in the body, allow insecure TLS |
+| `tcp`  | A host and port accept a connection     |                                                                                   |
+| `icmp` | A host answers ping                     |                                                                                   |
+| `tls`  | A certificate is valid and not expiring | warn N days before expiry                                                         |
+
+An `http` monitor with a keyword is usually the one you want for an application:
+a 200 that returns an error page still fails the keyword.
+
+## Where a check runs
+
+Every monitor has a **runner**:
+
+| Runner      | Meaning                                                        |
+| ----------- | -------------------------------------------------------------- |
+| `server`    | The control plane's scheduler performs the check               |
+| a server ID | That server's agent performs it locally and reports the result |
+
+Use `server` for anything reachable from the control plane public endpoints,
+your own front door. Use an agent for anything only reachable from inside the
+target network: a database on a private subnet, a service bound to localhost, a
+device on a management VLAN.
+
+:::tip Agent-run monitors measure what your users can't
+A check run from the control plane tells you the service is reachable from
+there. A check run on the machine tells you the process is alive. Those are
+different questions, and outages usually live in the gap.
+:::
+
+## Interval, retries and state
+
+- **Interval** how often to check.
+- **Retries** how many consecutive failures are tolerated before the state
+  flips.
+
+A monitor sits in `pending` until its first result. Failures accumulate; once
+they exceed `retries`, the monitor goes `down`, an **incident** opens and the
+attached notification channels fire. A subsequent success closes the incident.
+
+Retries are what keeps one dropped packet from paging you. Set them to at least
+`1` for anything crossing the public internet.
+
+## Notifications
+
+Attach one or more [notification channels](./notification-channels.md) to a
+monitor. Channels are shared, so one Slack destination can serve every monitor
+you have.
+
+Notification state is tracked per monitor, so a service that is down for six
+hours does not send a message per interval.
+
+## Uptime and incidents
+
+The monitor detail page shows:
+
+- **Uptime**, from hourly rollup records checks performed, how many were up,
+  and mean latency per hour. Rollups are what make the graph cheap to draw over
+  long windows.
+- **Incidents**, each with a start, a resolution and the cause recorded at the
+  moment it opened.
+
+## Disabling versus deleting
+
+Disabling stops the checks and keeps the history. Deleting removes the monitor.
+Prefer disabling for anything seasonal the uptime record is usually the part
+you wanted.

docsite/docs/vantage/notification-channels.md

@@ -0,0 +1,101 @@
+---
+id: notification-channels
+title: Notification channels
+sidebar_label: Notification channels
+---
+
+A channel is a destination for alerts. [Monitors](./monitors.md) reference
+channels by ID, so one destination serves as many monitors as you like.
+
+Manage them at **Settings → Notifications**.
+
+## Types
+
+### Webhook
+
+Posts JSON to a URL you choose.
+
+| Setting |          |
+| ------- | -------- |
+| `url`   | Required |
+
+```json
+{
+    "monitor": "API front door",
+    "type": "http",
+    "old_status": "up",
+    "new_status": "down",
+    "message": "HTTP 502",
+    "time": "2026-07-28T09:14:02Z"
+}
+```
+
+Any response of 300 or above counts as a delivery failure. The request times out
+after 10 seconds.
+
+### Discord
+
+| Setting |                     |
+| ------- | ------------------- |
+| `url`   | Discord webhook URL |
+
+Posts the alert as message content.
+
+### Slack
+
+| Setting |                            |
+| ------- | -------------------------- |
+| `url`   | Slack incoming webhook URL |
+
+### Telegram
+
+| Setting   |             |
+| --------- | ----------- |
+| `token`   | Bot token   |
+| `chat_id` | Target chat |
+
+### SMTP
+
+| Setting                |                                                      |
+| ---------------------- | ---------------------------------------------------- |
+| `host`, `port`         | Required                                             |
+| `from`, `to`           | Required                                             |
+| `username`, `password` | Optional; auth is skipped when the username is empty |
+
+Port `465` uses implicit TLS; anything else uses STARTTLS.
+
+Alert emails are rendered by the same email system that sends licence and
+account mail, so a monitor alert and an account email look like the same
+product.
+
+## The message
+
+Non-webhook channels all send the same one-line title:
+
+```
+[Vantage] API front door (http) is DOWN: HTTP 502
+```
+
+Recoveries read `recovered` in place of `is DOWN`. The webhook payload carries
+the same information as fields, which is the one to use if you are routing into
+something that needs to branch on status.
+
+## Testing
+
+Every channel has a **Test** button. It dispatches a fabricated down event for a
+monitor called "Test monitor", through the real delivery path so a test that
+arrives proves the credentials, the network path and the destination, not just
+the configuration form.
+
+:::tip Test after every change
+Channel settings are only exercised when something breaks, which is the worst
+time to discover a stale webhook URL. Re-test after rotating a token.
+:::
+
+## Choosing destinations
+
+- Use a **chat channel** for awareness, and make sure someone owns it.
+- Use **SMTP** where a durable record matters.
+- Use a **webhook** to reach an on-call system that does escalation properly.
+  Vantage does not do escalation, rotas or acknowledgement; a webhook into
+  something that does is the intended answer.

docsite/docs/vantage/secrets.md

@@ -0,0 +1,74 @@
+---
+id: secrets
+title: Secrets vault
+sidebar_label: Secrets
+---
+
+Key/value pairs, grouped by name, encrypted at rest with AES-256-GCM under
+`KEY_ENCRYPTION_KEY`. Two things consume them: workflow steps, and Kubernetes
+External Secrets Operator.
+
+## Groups and values
+
+A **group** is a named bundle `prod-db`, `registry`, `acme-api`. Inside it are
+key/value pairs.
+
+Group by consumer, not by type. A group is the unit a workflow step references
+and the unit ESO reads, so a group that matches one consumer is one reference;
+a group holding everything is over-sharing to every step that needs any of it.
+
+## Managing them
+
+**Secrets → New group**, then add keys.
+
+Values are write-then-hidden. The list shows keys, never values. **Reveal** is a
+separate action on a separate endpoint, and it writes an audit event so
+looking at a secret is a recorded act.
+
+Deleting a single key and deleting the whole group are separate operations.
+
+## Using secrets in workflows
+
+Add the group name to a step's `secret_refs`. At execution the group's pairs are
+injected into the step's environment:
+
+```bash
+# secret_refs: ["registry"]
+echo "$REGISTRY_PASSWORD" | docker login registry.example.com -u "$REGISTRY_USER" --password-stdin
+```
+
+A workflow can also override `secret_refs` per step, without changing the
+library entry.
+
+:::warning A step can print its own secrets
+Injection puts values in the environment. If your script echoes them, or runs
+with `set -x`, they land in the run log which is stored on disk and readable
+in the UI. Vantage does not scrub step output.
+:::
+
+## Kubernetes External Secrets Operator
+
+`GET /api/secrets/:group/values` returns a group's pairs for ESO, authenticated
+with a **bearer token** rather than a session.
+
+1. Generate the token at **Settings → Integrations**. It is shown once; only its
+   SHA-256 is stored.
+2. Put it in a Kubernetes secret.
+3. Point an ESO `SecretStore` at the endpoint with that bearer token.
+
+The token is rotatable: generating a new one replaces the stored hash and
+invalidates the old one immediately.
+
+:::danger This token reads every group
+It is instance-wide, not scoped to one group. Treat it as a credential to the
+whole vault: store it as a secret in the cluster, never in a manifest in git,
+and rotate it when anyone with access leaves.
+:::
+
+## What the vault is not
+
+- **Not a password manager.** There is no sharing, expiry or per-user
+  visibility. Anyone who can sign in and reveal, can reveal.
+- **Not versioned.** Overwriting a value loses the previous one.
+- **Not recoverable without the key.** If `KEY_ENCRYPTION_KEY` is lost, so is
+  every value. Back it up separately from the database.

docsite/docs/vantage/servers.md

@@ -0,0 +1,98 @@
+---
+id: servers
+title: Servers
+sidebar_label: Servers
+---
+
+The fleet. Every managed machine runs an agent that connects outbound to the
+control plane, and everything else in Vantage keys, workflows, monitors,
+consoles targets these records.
+
+## Enrolling a server
+
+Covered step by step in [Add your first server](../getting-started/first-server.md).
+In short: **Servers → Add server** issues a single-use, one-hour token and shows
+a one-liner to run as root on the target machine.
+
+## Lifecycle
+
+| Status    | Meaning                                             |
+| --------- | --------------------------------------------------- |
+| `pending` | Enrolment created; the agent has not registered yet |
+| `active`  | The agent registered and is syncing                 |
+| `offline` | Last-seen passed the threshold                      |
+
+The offline sweep runs every two minutes, so a machine that has just gone away
+takes a little while to be marked as such. That delay is intentional a single
+missed poll is not an outage.
+
+## The server detail page
+
+### Keys
+
+Which SSH keys are assigned to this machine, and their state. See
+[SSH keys](./ssh-keys.md).
+
+### Inventory
+
+Agents report:
+
+| Data                                     | Refreshed        |
+| ---------------------------------------- | ---------------- |
+| CPU, memory, swap, load                  | every 30 seconds |
+| Partitions, kernel, full static snapshot | every 15 minutes |
+
+The two carry separate timestamps, so a stale static snapshot beside fresh
+metrics is normal rather than a fault.
+
+### OS updates
+
+Agents check for pending package updates hourly and report the count. From the
+server page you can:
+
+- **Apply updates** pushes `ApplyUpdatesCmd` down the command stream. The
+  agent runs the platform's package manager and reports back.
+- **Update agent** pushes `UpdateAgentCmd` with a target version; the agent
+  downloads the release, verifies it and replaces itself. See
+  [Agent updates](../operations/agent-updates.md).
+
+:::warning Applying updates is not scheduled or staged
+It runs now, on that machine. If you need ordering, health gates or a canary,
+build it as a [workflow](./workflows.md) instead that is what workflows exist
+for.
+:::
+
+### Console
+
+Opens a browser SSH, RDP or VNC session. See [Browser console](./browser-console.md).
+
+## Windows servers
+
+Windows agents register, heartbeat, run workflow steps and report inventory.
+They do not manage `authorized_keys` the poll loop stops after the heartbeat
+on any non-Linux host. This is a deliberate scope decision, not a gap being
+worked on.
+
+## Removing a server
+
+Deleting the server record removes it from the fleet. It does **not** uninstall
+the agent, which will keep trying to sync and failing. Uninstall it on the
+machine too:
+
+```bash
+systemctl disable --now vantage-agent
+rm -f /usr/local/bin/vantage-agent /etc/systemd/system/vantage-agent.service
+rm -rf /etc/vantage
+systemctl daemon-reload
+```
+
+Keys previously written to `authorized_keys` stay on disk, because the agent is
+no longer running to remove them. Revoke and let the agent apply the change
+**before** you delete the server if that matters to you.
+
+## Agent tokens
+
+Each server has its own token. The control plane stores only its SHA-256; the
+plaintext exists in the agent's `0600` config and nowhere else. There is no way
+to read a token back out of the control plane if one is lost, re-enrol the
+machine.

docsite/docs/vantage/settings.md

@@ -0,0 +1,113 @@
+---
+id: settings
+title: Settings
+sidebar_label: Settings
+---
+
+One page, three groups: **Access**, **Monitoring** and **Integrations**. Plus
+the licence, which has its own page.
+
+Settings require the `owner` or `admin` role.
+
+:::info Where instance settings went
+Members and single sign-on used to live at `/settings/instance`. They are now
+the Access group at the top of this page splitting "who can sign in" from "how
+this instance behaves" produced two half-pages and a nav entry nobody could
+distinguish from Settings. The old path still redirects.
+:::
+
+## Access
+
+### Members
+
+Add, remove and re-role the people who can sign in.
+
+| Role     | Can                                                  |
+| -------- | ---------------------------------------------------- |
+| `owner`  | Everything                                           |
+| `admin`  | Everything except owner-only settings                |
+| `member` | Servers, keys, workflows, monitors, secrets, console |
+
+Local members authenticate with email and a bcrypt-hashed password.
+
+#### Members managed by Vantage HQ
+
+On a cloud instance, people granted access from the HQ portal appear here as
+read-only rows with a link to the portal.
+
+:::warning HQ-managed users cannot be edited locally
+Changing the role of, or deleting, an `hq`-sourced user is refused with `409`.
+HQ owns their role, their password and whether they exist at all a local
+change would be overwritten by the next sync and would leave two writers for one
+password hash. Manage them from [People and roles](../hq/people-and-roles.md).
+:::
+
+### Single sign-on (OIDC)
+
+Configured per organisation:
+
+| Field         |                              |
+| ------------- | ---------------------------- |
+| Issuer        | Your provider's issuer URL   |
+| Client ID     |                              |
+| Client secret | Stored AES-256-GCM encrypted |
+
+Sign-in then goes `/auth/oidc/start` → your provider → `/auth/oidc/callback`.
+
+Local and OIDC users coexist. Keep at least one local owner: if the provider is
+misconfigured or unreachable, a local account is the way back in.
+
+## Monitoring
+
+- **Alert defaults** for monitors.
+- **Notification channels** their own page. See
+  [Notification channels](./notification-channels.md).
+
+## Integrations
+
+### Workflow log retention
+
+How long run logs are kept.
+
+| Value    | Meaning        |
+| -------- | -------------- |
+| unset    | 30 days        |
+| a number | that many days |
+| `0`      | forever        |
+
+### ESO read token
+
+The bearer token External Secrets Operator uses to read secret groups. Shown
+once, stored as a SHA-256 hash, rotatable. See
+[Secrets](./secrets.md#kubernetes-external-secrets-operator).
+
+## Licence
+
+`/settings/license` shows the deployment, tier, server allowance, enabled
+features and expiry.
+
+On **self-hosted**, paste a licence here. This works even while the current
+licence is expired that is the way out of degraded mode.
+
+On **cloud**, there is no paste form. The endpoint answers `409 cloud_managed`,
+because a cloud licence is written by HQ directly. The page links to the portal
+instead.
+
+See [Licensing and entitlements](../hq/licensing-and-entitlements.md).
+
+## Sessions
+
+Sessions are an opaque token in the `km_session` cookie, held in Redis with a
+24-hour TTL. There is no per-session management UI; restarting Redis signs
+everyone out and affects nothing else.
+
+## Host and organisation guard
+
+On a multi-tenant deployment, a request to `<slug>.vantage.<tld>` resolves the
+organisation from the slug and rejects a session belonging to a different one.
+The label it looks for comes from `APP_ROOT_LABEL`.
+
+:::warning A wrong `APP_ROOT_LABEL` disables the guard
+It does not fail loudly it simply stops matching, and the host check stops
+protecting anything. If you serve the UI on a custom domain, set it to match.
+:::

docsite/docs/vantage/ssh-keys.md

@@ -0,0 +1,81 @@
+---
+id: ssh-keys
+title: SSH keys
+sidebar_label: SSH keys
+---
+
+Vantage holds a library of public keys and decides, per server, which ones
+belong in `/root/.ssh/authorized_keys`. The agent makes the file match.
+
+:::info root only
+Vantage manages `/root/.ssh/authorized_keys` and nothing else. There is no
+per-user key management. The agent runs as root because writing that file
+requires it.
+:::
+
+## Adding a key
+
+### Upload one you already have
+
+**Keys → Add key**, paste the public half. Vantage stores the public key and its
+fingerprint, and never needs the private half for this path.
+
+### Generate one on a server
+
+Vantage can have an agent generate a keypair on a managed machine
+(`GenerateKeyCmd` over the command stream). The public half comes back to the
+library. You may optionally upload the private half too, in which case it is
+stored **AES-256-GCM encrypted** under `KEY_ENCRYPTION_KEY`.
+
+The JSON representation of a key exposes only `has_private_key` and
+`has_passphrase` never the material. Retrieving a stored private key is its
+own endpoint and its own audit event.
+
+:::tip Why store a private key at all
+The [browser console](./browser-console.md) needs one to open an SSH session. If
+you are not using the console, do not upload private halves.
+:::
+
+## Assigning
+
+Assign a key to one or more servers. Within one poll interval 30 seconds the
+agent picks up the change.
+
+## Revoking
+
+Revocation is **soft**: the assignment gets a `revoked_at` timestamp rather than
+being deleted, so the history of who had access to what, and when, survives.
+
+The agent treats a revoked assignment as "not desired" and removes the line from
+`authorized_keys` on its next sync.
+
+:::warning Revoking does not close open sessions
+It removes the key from the file. An SSH session already established stays up
+until it ends. Kill sessions on the machine if that matters.
+:::
+
+## What the agent actually does
+
+Each poll:
+
+1. The control plane returns the desired set of public keys for that server.
+2. The agent reads `/root/.ssh/authorized_keys` and computes fingerprints.
+3. **If the sets match, it writes nothing.** No disk churn on unchanged state,
+   which is most polls.
+4. If they differ, it writes a temporary file, then `os.Rename()`s it over the
+   real one and sets mode `0600`.
+
+The rename is atomic, so a machine that dies mid-write keeps the old file
+intact. There is no window in which `authorized_keys` is truncated or partial.
+
+:::danger Vantage owns the whole file
+The agent rewrites `authorized_keys` to match the desired set. Keys added by
+hand on the machine are removed on the next change. If a key must survive, put
+it in Vantage.
+:::
+
+## Recovering from a lockout
+
+If you have removed every key from a machine and cannot get in, you still have
+the console provided a private key is stored or out-of-band access from your
+hosting provider. Vantage has no backdoor and does not keep a break-glass key.

docsite/docs/vantage/workflows.md

@@ -0,0 +1,141 @@
+---
+id: workflows
+title: Workflows and steps
+sidebar_label: Workflows
+---
+
+A **step** is a reusable script with declared inputs, outputs and secret
+references. A **workflow** composes steps in order and targets a set of servers.
+Running one dispatches the steps to each target's agent and streams the output
+back live.
+
+## Steps
+
+A step has:
+
+| Field                 | Meaning                                         |
+| --------------------- | ----------------------------------------------- |
+| `name`, `description` | Library identity                                |
+| `interpreter`         | `bash` or `powershell`                          |
+| `script`              | The body                                        |
+| `declared_inputs`     | Named parameters with defaults and descriptions |
+| `declared_outputs`    | Names this step promises to export              |
+| `secret_refs`         | Vault entries injected as environment variables |
+
+### Passing values between steps
+
+Each step runs with `WORKFLOW_ENV` set to a file path. Anything written there as
+`KEY=value` becomes an environment variable for the **later steps of the same
+run on the same server**.
+
+```bash
+HOSTNAME=$(hostname)
+echo "$HOSTNAME"
+echo "HOSTNAME=$HOSTNAME" >> $WORKFLOW_ENV
+```
+
+That is the whole mechanism. `declared_outputs` documents what a step exports so
+the designer can show it; the file is what actually carries the value.
+
+### Secrets
+
+List a vault group in `secret_refs` and its key/value pairs are injected as
+environment variables when the step runs. They are not written to the run log
+unless your own script echoes them. See [Secrets](./secrets.md).
+
+### The workspace
+
+Every run gets a per-run working directory on each target. Steps share it, so
+one step can leave a file for the next. The agent removes it at the end of the
+run (`CleanupWorkspaceCmd`).
+
+Do not use it for anything that must outlive the run.
+
+## Default steps
+
+A small library is seeded into every organisation at boot from the image, so a
+new install is not staring at an empty page.
+
+:::warning Default steps are read-only
+Editing or deleting one is refused with `409`. Seeding rewrites them on every
+boot, so an edit would silently revert and a delete would come back at the next
+restart refusing is the honest answer.
+
+To customise one, use the per-step **script override** in the workflow designer,
+which belongs to that workflow and is not touched by seeding. To add to the
+shared library permanently, a file has to be committed to the repository and the
+server image rebuilt.
+:::
+
+The UI mirrors this the step modal opens read-only and Delete is hidden but
+the API is the boundary; the UI is the courtesy.
+
+## Building a workflow
+
+1. **Workflows → New**.
+2. Add steps in order from the library.
+3. Set inputs per step.
+4. Set failure behaviour per step.
+5. Choose target servers.
+
+### Failure behaviour
+
+| `on_failure` | Effect                                                          |
+| ------------ | --------------------------------------------------------------- |
+| `stop`       | Abort this server's run. Other servers continue                 |
+| `continue`   | Record the failure, run the next step anyway                    |
+| `retry`      | Re-run the step up to `max_retries`, then treat it as a failure |
+
+### Per-step overrides
+
+A workflow can override a step's script or its secret references without
+touching the library entry. This is how you adapt a default step, and it is
+scoped to that workflow.
+
+## Running
+
+**Run** snapshots the resolved steps into the run record and dispatches each step
+to the target's agent over the command stream no waiting for the next poll.
+
+:::info Runs freeze their steps
+The snapshot is why editing a step tomorrow never rewrites what happened today.
+A run shows the script that actually executed, not the current library version.
+:::
+
+Targets run **in parallel**; steps within one server run **in order**.
+
+## Watching a run
+
+Step stdout and stderr stream back as chunks, are appended to a log file on the
+server, and the UI follows them live. Each step records status, attempts, exit
+code and its exported environment.
+
+**Cancel** stops a run in progress. Steps already running on an agent finish;
+nothing further is dispatched.
+
+## Log retention
+
+Run logs are swept on a schedule set by `workflow_log_retention_days` in
+Settings:
+
+| Value    | Meaning        |
+| -------- | -------------- |
+| unset    | 30 days        |
+| a number | that many days |
+| `0`      | keep forever   |
+
+## Import and export
+
+Steps export to a JSON file (`vantage.step/v1`) and import back, which is how
+you move a step between instances or keep one in version control. There is also
+a parse endpoint that turns a pasted script into a draft step by reading its
+declared inputs and outputs.
+
+## Practical notes
+
+- A step is a script. It runs as root, on the target, with no sandbox. Review
+  what you import.
+- Keep steps small and single-purpose; compose them in the workflow. That is
+  what makes the library reusable rather than a folder of near-duplicates.
+- PowerShell steps only make sense on Windows targets and bash steps on Linux
+  ones. Nothing stops you targeting the wrong one; the step simply fails.

docsite/docusaurus.config.ts

@@ -0,0 +1,123 @@
+import type * as Preset from "@docusaurus/preset-classic";
+import type { Config } from "@docusaurus/types";
+import { themes as prismThemes } from "prism-react-renderer";
+
+// Served as a path on the marketing host (vantage.hostxtra.co.uk/docs), routed
+// by its own Nginx Proxy Manager location rather than by site/. A path and not
+// a subdomain on purpose: *.vantage.hostxtra.co.uk is the per-tenant instance
+// namespace, and APP_ROOT_LABEL resolves an org from the label before
+// "vantage", so a docs. label there would be read as a tenant slug.
+//
+// DOCS_BASE_URL has to agree with three things at once: the NPM location, the
+// directory the runtime image copies the build into, and this value. When they
+// disagree the HTML still loads and every asset 404s.
+const url = process.env.DOCS_URL || "https://vantage.hostxtra.co.uk";
+const baseUrl = process.env.DOCS_BASE_URL || "/docs/";
+const appUrl = process.env.APP_URL || "https://vantage.hostxtra.co.uk";
+const hqUrl = process.env.HQ_URL || "https://vantage-hq.hostxtra.co.uk";
+
+const config: Config = {
+    title: "Vantage Docs",
+    tagline: "Fleet management for servers you actually own",
+    favicon: "img/favicon.svg",
+
+    url,
+    baseUrl,
+
+    organizationName: "hostxtra",
+    projectName: "vantage",
+
+    onBrokenLinks: "throw",
+    onBrokenAnchors: "throw",
+
+    i18n: { defaultLocale: "en", locales: ["en"] },
+
+    markdown: {
+        mermaid: true,
+        hooks: { onBrokenMarkdownLinks: "throw" },
+    },
+    themes: [
+        "@docusaurus/theme-mermaid",
+        [
+            // Compile-time index served from this origin. No Algolia account,
+            // no external host, nothing to key or rotate.
+            "@easyops-cn/docusaurus-search-local",
+            {
+                hashed: true,
+                indexBlog: false,
+                docsRouteBasePath: "/",
+                highlightSearchTermsOnTargetPage: true,
+            },
+        ],
+    ],
+
+    presets: [
+        [
+            "classic",
+            {
+                docs: {
+                    // Docs-only mode: the documentation is the site.
+                    routeBasePath: "/",
+                    sidebarPath: "./sidebars.ts",
+                },
+                blog: false,
+                theme: { customCss: "./src/css/custom.css" },
+            } satisfies Preset.Options,
+        ],
+    ],
+
+    themeConfig: {
+        colorMode: {
+            // Light default, matching site/ and adminsite/. web/ is the only
+            // app locked to dark, and that contrast is deliberate.
+            defaultMode: "light",
+            respectPrefersColorScheme: true,
+        },
+        navbar: {
+            // Wordmark only. The logo mark is drawn with currentColor in
+            // site/components/Logo.tsx, which an <img> src cannot inherit, and
+            // baking a fill into the file would mean a hex that stops tracking
+            // the theme.
+            title: "Vantage",
+            items: [
+                {
+                    type: "docSidebar",
+                    sidebarId: "docs",
+                    position: "left",
+                    label: "Documentation",
+                },
+                { href: appUrl, label: "Control plane", position: "right" },
+                { href: hqUrl, label: "Vantage HQ", position: "right" },
+            ],
+        },
+        footer: {
+            style: "light",
+            links: [
+                {
+                    title: "Documentation",
+                    items: [
+                        { label: "Getting started", to: "/getting-started/what-is-vantage" },
+                        { label: "Vantage", to: "/vantage/servers" },
+                        { label: "Vantage HQ", to: "/hq/accounts-and-signup" },
+                        { label: "Reference", to: "/reference/environment-variables" },
+                    ],
+                },
+                {
+                    title: "Product",
+                    items: [
+                        { label: "Control plane", href: appUrl },
+                        { label: "Vantage HQ", href: hqUrl },
+                    ],
+                },
+            ],
+            copyright: `© ${new Date().getFullYear()} HostXtra.`,
+        },
+        prism: {
+            theme: prismThemes.github,
+            darkTheme: prismThemes.dracula,
+            additionalLanguages: ["bash", "powershell", "yaml", "json", "protobuf", "nginx"],
+        },
+    } satisfies Preset.ThemeConfig,
+};
+
+export default config;

docsite/nginx.conf

@@ -0,0 +1,32 @@
+server {
+    listen 80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Hitting the container directly is a 403 on an empty document root
+    # otherwise, which reads as a broken deploy rather than "wrong path".
+    location = / {
+        return 302 /docs/;
+    }
+
+    # Hashed assets are immutable — the filename changes when the content does.
+    location /docs/assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+        try_files $uri =404;
+    }
+
+    location /docs/ {
+        # Docusaurus emits a real page per route, so a miss is a genuine 404
+        # rather than something a SPA fallback should paper over.
+        try_files $uri $uri/ $uri.html /docs/404.html;
+    }
+
+    error_page 404 /docs/404.html;
+
+    gzip on;
+    gzip_types text/plain text/css application/javascript application/json image/svg+xml;
+    gzip_min_length 1024;
+}

docsite/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "vantage-docs",
+    "version": "0.1.0",
+    "private": true,
+    "scripts": {
+        "start": "docusaurus start",
+        "build": "docusaurus build",
+        "serve": "docusaurus serve",
+        "clear": "docusaurus clear",
+        "typecheck": "tsc"
+    },
+    "dependencies": {
+        "@docusaurus/core": "^3.10.2",
+        "@docusaurus/preset-classic": "^3.10.2",
+        "@docusaurus/theme-mermaid": "^3.10.2",
+        "@easyops-cn/docusaurus-search-local": "^0.52.1",
+        "@mdx-js/react": "^3.0.0",
+        "clsx": "^2.1.1",
+        "prism-react-renderer": "^2.3.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    },
+    "devDependencies": {
+        "@docusaurus/module-type-aliases": "^3.10.2",
+        "@docusaurus/tsconfig": "^3.10.2",
+        "@docusaurus/types": "^3.10.2",
+        "typescript": "~5.6.2"
+    },
+    "browserslist": {
+        "production": [
+            ">0.5%",
+            "not dead",
+            "not op_mini all"
+        ],
+        "development": [
+            "last 3 chrome version",
+            "last 3 firefox version",
+            "last 5 safari version"
+        ]
+    },
+    "engines": {
+        "node": ">=20.0"
+    }
+}

docsite/sidebars.ts

@@ -0,0 +1,54 @@
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+// Authored by hand rather than autogenerated, so ordering is a decision and
+// not a filename accident.
+const sidebars: SidebarsConfig = {
+    docs: [
+        "index",
+        {
+            type: "category",
+            label: "Getting started",
+            collapsed: false,
+            items: [
+                "getting-started/what-is-vantage",
+                "getting-started/cloud-vs-self-hosted",
+                "getting-started/self-hosted-install",
+                "getting-started/first-login",
+                "getting-started/first-server",
+                "getting-started/claim-free-licence",
+            ],
+        },
+        {
+            type: "category",
+            label: "Vantage",
+            items: [
+                "vantage/servers",
+                "vantage/ssh-keys",
+                "vantage/workflows",
+                "vantage/monitors",
+                "vantage/notification-channels",
+                "vantage/secrets",
+                "vantage/browser-console",
+                "vantage/audit-log",
+                "vantage/settings",
+            ],
+        },
+        {
+            type: "category",
+            label: "Vantage HQ",
+            items: ["hq/accounts-and-signup", "hq/people-and-roles", "hq/cloud-instances", "hq/self-hosted-instances", "hq/licensing-and-entitlements", "hq/billing", "hq/free-tier"],
+        },
+        {
+            type: "category",
+            label: "Reference",
+            items: ["reference/environment-variables", "reference/rest-api", "reference/agent-config", "reference/ports-and-networking", "reference/troubleshooting"],
+        },
+        {
+            type: "category",
+            label: "Operations",
+            items: ["operations/upgrading", "operations/backups", "operations/agent-updates"],
+        },
+    ],
+};
+
+export default sidebars;

docsite/src/css/custom.css

@@ -0,0 +1,236 @@
+/* ==========================================================================
+   Vantage documentation design tokens
+
+   The token block below is COPIED VERBATIM from site/app/globals.css — same
+   names, same values. adminsite/ holds a copy too, web/ holds the dark half,
+   and shared/mail/templates/layout.html.tmpl holds it a fifth time as literal
+   hex because email clients support neither var() nor prefers-color-scheme.
+   Nothing enforces the match automatically: change a token in one file and you
+   change it in all of them, in the same commit.
+
+   Everything below the token block maps Docusaurus's --ifm-* variables onto
+   these. No rule in this file, and no component in this app, may carry a hex
+   value outside the two token blocks.
+
+   Docusaurus always stamps data-theme on <html>, so unlike site/ there is no
+   prefers-color-scheme branch to keep in step — the theme toggle is the only
+   writer.
+   ========================================================================== */
+
+:root,
+:root[data-theme="light"] {
+    --ground: #eaedf3;
+    --panel: #ffffff;
+    --panel-2: #f4f6fa;
+    --ink: #0a1b33;
+    --ink-2: #41556f;
+    --ink-3: #6c7f96;
+    --rule: #cdd6e2;
+    --rule-soft: #e0e6ef;
+    --accent: #0b2a58;
+    --accent-ink: #ffffff;
+    --up: #2f8a60;
+    --down: #c6462f;
+    --pend: #b0801f;
+    --shadow: 0 1px 0 rgba(10, 27, 51, 0.05), 0 18px 40px -26px rgba(10, 27, 51, 0.45);
+    --logo: #0b2a58;
+
+    --sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --mono: ui-monospace, "Cascadia Mono", "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace;
+
+    --s--1: clamp(0.76rem, 0.74rem + 0.1vw, 0.81rem);
+    --s-0: clamp(1rem, 0.97rem + 0.14vw, 1.05rem);
+    --s-1: clamp(1.16rem, 1.09rem + 0.32vw, 1.36rem);
+    --s-2: clamp(1.5rem, 1.34rem + 0.74vw, 2rem);
+    --s-3: clamp(2rem, 1.66rem + 1.6vw, 3.1rem);
+    --s-4: clamp(2.6rem, 1.9rem + 3.3vw, 4.9rem);
+
+    --rail: 1200px;
+}
+
+:root[data-theme="dark"] {
+    --ground: #071628;
+    --panel: #0d2138;
+    --panel-2: #102842;
+    --ink: #e4ecf6;
+    --ink-2: #9fb3ca;
+    --ink-3: #71879f;
+    --rule: #1e3855;
+    --rule-soft: #172c44;
+    --accent: #5b9be8;
+    --accent-ink: #04101f;
+    --up: #4fb484;
+    --down: #e2705a;
+    --pend: #d6a63f;
+    --shadow: 0 1px 0 rgba(0, 0, 0, 0.35), 0 20px 44px -26px rgba(0, 0, 0, 0.85);
+    --logo: #7fb2f0;
+}
+
+/* ---------- Docusaurus mapping ---------- */
+
+:root {
+    --ifm-color-primary: var(--accent);
+    --ifm-color-primary-dark: var(--accent);
+    --ifm-color-primary-darker: var(--accent);
+    --ifm-color-primary-darkest: var(--accent);
+    --ifm-color-primary-light: var(--accent);
+    --ifm-color-primary-lighter: var(--accent);
+    --ifm-color-primary-lightest: var(--accent);
+
+    --ifm-background-color: var(--ground);
+    --ifm-background-surface-color: var(--panel);
+
+    --ifm-font-family-base: var(--sans);
+    --ifm-font-family-monospace: var(--mono);
+    --ifm-font-size-base: var(--s-0);
+    --ifm-line-height-base: 1.65;
+
+    --ifm-heading-font-weight: 800;
+    --ifm-heading-line-height: 1.15;
+    --ifm-h1-font-size: var(--s-3);
+    --ifm-h2-font-size: var(--s-2);
+    --ifm-h3-font-size: var(--s-1);
+
+    --ifm-font-color-base: var(--ink);
+    --ifm-heading-color: var(--ink);
+    --ifm-link-color: var(--accent);
+    --ifm-link-hover-color: var(--accent);
+    --ifm-toc-link-color: var(--ink-2);
+
+    --ifm-navbar-background-color: var(--panel);
+    --ifm-navbar-shadow: none;
+    --ifm-navbar-link-color: var(--ink-2);
+    --ifm-navbar-link-hover-color: var(--ink);
+
+    --ifm-footer-background-color: var(--panel-2);
+    --ifm-footer-color: var(--ink-2);
+    --ifm-footer-link-color: var(--ink-2);
+    --ifm-footer-title-color: var(--ink);
+
+    --ifm-menu-color: var(--ink-2);
+    --ifm-menu-color-active: var(--accent);
+    --ifm-menu-color-background-active: var(--panel-2);
+    --ifm-menu-color-background-hover: var(--panel-2);
+
+    --ifm-toc-border-color: var(--rule-soft);
+    --ifm-hr-border-color: var(--rule-soft);
+    --ifm-table-border-color: var(--rule-soft);
+    --ifm-table-stripe-background: var(--panel-2);
+    --ifm-table-head-background: var(--panel-2);
+
+    --ifm-code-background: var(--panel-2);
+    --ifm-code-font-size: 0.88em;
+    --ifm-pre-background: var(--panel-2);
+    --ifm-blockquote-color: var(--ink-2);
+    --ifm-blockquote-border-color: var(--rule);
+
+    --ifm-global-radius: 4px;
+    --ifm-alert-border-radius: 4px;
+    --ifm-button-border-radius: 4px;
+    --ifm-global-shadow-lw: var(--shadow);
+    --ifm-global-shadow-md: var(--shadow);
+
+    --ifm-breadcrumb-color-active: var(--accent);
+    --ifm-breadcrumb-item-background-active: var(--panel-2);
+
+    --docusaurus-highlighted-code-line-bg: var(--rule-soft);
+}
+
+/* Admonitions carry the semantic three. They read by shape and label as well
+   as colour, which is the rule everywhere else in the product too. */
+.theme-admonition-note,
+.theme-admonition-info {
+    --ifm-alert-background-color: var(--panel-2);
+    --ifm-alert-border-color: var(--rule);
+    --ifm-alert-foreground-color: var(--ink);
+}
+
+.theme-admonition-tip {
+    --ifm-alert-background-color: var(--panel-2);
+    --ifm-alert-border-color: var(--up);
+    --ifm-alert-foreground-color: var(--ink);
+}
+
+.theme-admonition-warning {
+    --ifm-alert-background-color: var(--panel-2);
+    --ifm-alert-border-color: var(--pend);
+    --ifm-alert-foreground-color: var(--ink);
+}
+
+.theme-admonition-danger {
+    --ifm-alert-background-color: var(--panel-2);
+    --ifm-alert-border-color: var(--down);
+    --ifm-alert-foreground-color: var(--ink);
+}
+
+/* ---------- small corrections ---------- */
+
+.navbar {
+    border-bottom: 1px solid var(--rule-soft);
+}
+
+.navbar__title {
+    font-weight: 800;
+    letter-spacing: -0.02em;
+}
+
+.footer {
+    border-top: 1px solid var(--rule-soft);
+}
+
+.markdown h1,
+.markdown h2,
+.markdown h3 {
+    letter-spacing: -0.03em;
+    text-wrap: balance;
+}
+
+.markdown h2 {
+    margin-top: 2.4rem;
+    padding-top: 1.6rem;
+    border-top: 1px solid var(--rule-soft);
+}
+
+.markdown > p,
+.markdown li {
+    color: var(--ink-2);
+}
+
+.markdown strong {
+    color: var(--ink);
+}
+
+/* Machine output — install one-liners, key blobs, run logs — sits on a floor
+   beneath the panel, the same distinction web/ draws with --well. */
+.theme-code-block {
+    border: 1px solid var(--rule-soft);
+    box-shadow: none !important;
+}
+
+table {
+    display: table;
+    width: 100%;
+}
+
+.menu {
+    font-size: var(--s--1);
+    padding: 1rem;
+}
+
+.menu__list-item-collapsible .menu__link--sane,
+.menu__link {
+    border-radius: 4px;
+}
+
+:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 3px;
+}
+
+/* The reference tables in Reference/ are wide by nature; they scroll inside
+   their own container rather than pushing the page sideways. */
+.markdown table {
+    display: block;
+    overflow-x: auto;
+    max-width: 100%;
+}

docsite/static/img/favicon.svg

@@ -0,0 +1,12 @@
+<!--
+  The Vantage mark, traced from site/components/Logo.tsx. A favicon is an asset
+  rather than a component, and a browser tab has no access to the token block,
+  so the logo navy is a literal here — the same concession the email layout
+  makes. Keep it in step with --logo.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="246 207 533 610">
+  <g transform="translate(0,1024) scale(0.1,-0.1)" fill="#0b2a58" stroke="none">
+    <path d="M4940 7767 c-96 -57 -528 -312 -960 -567 -678 -400 -1064 -628 -1187 -702 l-33 -20 0 -1357 0 -1357 293 -174 c160 -96 425 -252 587 -348 946 -559 1352 -799 1407 -833 34 -22 67 -39 72 -39 5 0 188 106 408 236 219 130 459 272 533 315 74 44 425 252 780 462 l645 382 0 1355 0 1355 -135 81 c-140 84 -1118 662 -1812 1070 -218 129 -402 236 -410 239 -7 3 -92 -42 -188 -98z m297 -331 c309 -182 971 -572 1208 -712 149 -88 372 -220 498 -294 l227 -135 0 -1175 0 -1175 -578 -342 c-317 -188 -694 -411 -837 -495 -143 -85 -344 -204 -447 -265 l-186 -111 -314 185 c-987 584 -1710 1013 -1725 1025 -10 8 -13 256 -13 1178 0 1099 1 1168 18 1182 9 8 150 93 312 188 162 96 417 246 565 333 805 476 1149 677 1156 677 4 0 56 -29 116 -64z" />
+    <path d="M3760 6109 c0 -6 187 -396 417 -867 229 -471 483 -994 564 -1162 l148 -305 232 0 233 0 271 560 c150 308 403 830 564 1160 160 329 291 605 291 612 0 19 -553 19 -568 1 -9 -12 -229 -480 -652 -1390 -73 -158 -136 -285 -140 -283 -3 2 -100 206 -215 452 -115 246 -291 624 -390 838 l-182 390 -287 3 c-202 2 -286 -1 -286 -9z" />
+  </g>
+</svg>

docsite/tsconfig.json

@@ -0,0 +1,7 @@
+{
+    "extends": "@docusaurus/tsconfig",
+    "compilerOptions": {
+        "baseUrl": "."
+    },
+    "exclude": [".docusaurus", "build"]
+}

proto/vantage/v1/vantage.proto

@@ -2,18 +2,19 @@ syntax = "proto3";
 
 package vantage.v1;
 
-option go_package = "gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/grpc/pb";
+option go_package="gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/grpc/pb";
 
 service Vantage {
   rpc Register(RegisterRequest)                returns (RegisterResponse);
   rpc SyncKeys(SyncRequest)                    returns (SyncResponse);
   rpc UploadGeneratedKey(UploadKeyRequest)      returns (UploadKeyResponse);
   rpc ReportUpdates(ReportUpdatesRequest)       returns (ReportUpdatesResponse);
-  rpc ReportInventory(InventoryReport)          returns (InventoryReportResponse);
+  rpc ReportInventory(InventoryReport)        returns (InventoryReportResponse);
   rpc SyncMonitors(SyncMonitorsRequest)         returns (SyncMonitorsResponse);
   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 {
@@ -63,7 +64,9 @@ message AgentMessage {
   }
 }
 
-message AgentReady {}
+message AgentReady {
+
+}
 
 message CommandResult {
   string command_id = 1;
@@ -83,7 +86,9 @@ message ReportUpdatesRequest {
   repeated PackageUpdate updates = 3;
 }
 
-message ReportUpdatesResponse {}
+message ReportUpdatesResponse {
+
+}
 
 message CPUReport {
   string model     = 1;
@@ -117,7 +122,9 @@ message InventoryReport {
   string kernel         = 9;
 }
 
-message InventoryReportResponse {}
+message InventoryReportResponse {
+
+}
 
 message MonitorSpec {
   string monitor_id      = 1;
@@ -157,9 +164,13 @@ message ReportChecksRequest {
   repeated CheckResult results = 3;
 }
 
-message ReportChecksResponse {}
+message ReportChecksResponse {
 
-message ApplyUpdatesCmd {}
+}
+
+message ApplyUpdatesCmd {
+
+}
 
 message ServerCommand {
   string command_id = 1;
@@ -170,6 +181,7 @@ message ServerCommand {
     ApplyUpdatesCmd apply_updates = 5;
     RunStepCmd      run_step      = 6;
     CleanupWorkspaceCmd cleanup_workspace = 7;
+    OpenProxyCmd open_proxy = 8;
   }
 }
 
@@ -201,7 +213,7 @@ message RunStepCmd {
   string script           = 2;
   map<string, string> env = 3;
   int32  timeout_seconds  = 4;
-  string workspace_id     = 5; // per-run working dir the agent creates & uses as cwd
+  string workspace_id     = 5; 
 }
 
 message StepResult {
@@ -218,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/Dockerfile

@@ -24,6 +24,9 @@ FROM scratch
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 COPY --from=builder /vantage-server /vantage-server
 
+COPY default_steps/ /opt/default-steps/
+ENV VANTAGE_DEFAULT_STEPS_DIR=/opt/default-steps
+
 EXPOSE 8080 9090
 
 ENTRYPOINT ["/vantage-server"]

server/cmd/main.go

@@ -4,10 +4,12 @@ import (
 	"context"
 	"log"
 	"os"
+	"strings"
 	"time"
 
 	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/api"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/bus"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/db"
 	grpcserver "gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/grpc"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/monitorsched"
@@ -18,7 +20,21 @@ import (
 func main() {
 	mongoURI := getEnv("MONGO_URI", "mongodb://localhost:27017")
 
-	if os.Getenv("GRPC_HOST") == "" {
+	// Two flags, so the schema work can be lifted out of the serving pods.
+	//
+	// Under Docker Compose neither is set and nothing changes: one process
+	// migrates and then serves. Under Kubernetes with more than one replica
+	// that is unsafe — every pod would run MigrateOrgToInstance at once, and
+	// renaming collections while a sibling reads them is not a race anyone
+	// wins. The chart therefore runs a pre-upgrade Job with MIGRATE_ONLY and
+	// starts the Deployment with SKIP_MIGRATIONS.
+	migrateOnly := boolEnv("VANTAGE_MIGRATE_ONLY")
+	skipMigrations := boolEnv("VANTAGE_SKIP_MIGRATIONS")
+
+	// Not required in migrate-only mode: that process never serves gRPC, and
+	// demanding it would put an agent-facing address in a Job that has no
+	// business knowing one.
+	if !migrateOnly && os.Getenv("GRPC_HOST") == "" {
 		log.Fatal("GRPC_HOST is required (host:port agents dial for gRPC)")
 	}
 
@@ -28,6 +44,24 @@ func main() {
 	}
 	log.Println("connected to MongoDB")
 
+	if migrateOnly || !skipMigrations {
+		runSchemaSetup()
+	} else {
+		log.Println("VANTAGE_SKIP_MIGRATIONS set: assuming migrations ran elsewhere")
+	}
+
+	if migrateOnly {
+		log.Println("VANTAGE_MIGRATE_ONLY set: schema setup complete, exiting")
+		return
+	}
+
+	serve()
+}
+
+// runSchemaSetup performs every write that must happen exactly once before the
+// application serves: migrations, index builders and default step seeding. It
+// is fatal on anything that would leave the schema half-moved.
+func runSchemaSetup() {
 	// Migrations 0001 to 0003 still speak the pre-rename shape (orgs, org_id),
 	// so they must run before 0004 renames everything underneath them.
 	if err := services.RunMigrations(); err != nil {
@@ -87,24 +121,27 @@ func main() {
 		}
 	}
 
-	services.StartLogSweeper()
-	services.StartAuditSweeper()
+}
 
+func serve() {
 	redisAddr := getEnv("REDIS_ADDR", "localhost:6379")
-	if err := auth.InitRedis(redisAddr); err != nil {
+	redisUser := os.Getenv("REDIS_USERNAME")
+	redisPass := os.Getenv("REDIS_PASSWORD")
+	if err := auth.InitRedis(redisAddr, redisUser, redisPass); err != nil {
 		log.Fatalf("failed to connect to Redis: %v", err)
 	}
 	log.Println("connected to Redis")
 
-	go func() {
-		ticker := time.NewTicker(2 * time.Minute)
-		defer ticker.Stop()
-		for range ticker.C {
-			if err := services.MarkOfflineServers(); err != nil {
-				log.Printf("mark offline error: %v", err)
-			}
-		}
-	}()
+	// The bus carries agent commands and step results between replicas. It is
+	// not optional even on a single-replica deployment: dispatch takes the same
+	// path either way, so the code exercised in production is the code
+	// exercised everywhere.
+	if err := bus.Init(redisAddr, redisUser, redisPass); err != nil {
+		log.Fatalf("failed to connect the message bus: %v", err)
+	}
+	log.Printf("message bus ready as node %s", bus.NodeID())
+
+	ctx := context.Background()
 
 	go func() {
 		if err := grpcserver.StartGRPC(9090); err != nil {
@@ -112,9 +149,33 @@ func main() {
 		}
 	}()
 
-	monitorsched.Start(context.Background())
+	// Everything below runs on exactly one replica at a time.
+	//
+	// These are cluster-singleton jobs, not per-pod work: N replicas would mean
+	// every monitor check firing N times, every incident notification delivered
+	// to the customer N times, every retention sweep deleting concurrently, and
+	// N reapers racing to purge the same instance. They share one lock rather
+	// than holding four, because they are one role — housekeeping — and
+	// splitting them would only spread that role across pods for no benefit.
+	bus.RunAsLeader(ctx, "housekeeping", func(jobCtx context.Context) {
+		services.StartLogSweeper(jobCtx)
+		services.StartAuditSweeper(jobCtx)
+		services.StartReaper(jobCtx)
+		monitorsched.Start(jobCtx)
 
-	services.StartReaper(context.Background())
+		ticker := time.NewTicker(2 * time.Minute)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-jobCtx.Done():
+				return
+			case <-ticker.C:
+				if err := services.MarkOfflineServers(); err != nil {
+					log.Printf("mark offline error: %v", err)
+				}
+			}
+		}
+	})
 
 	r := gin.New()
 	r.Use(gin.Recovery())
@@ -147,3 +208,14 @@ func getEnv(key, fallback string) string {
 	}
 	return fallback
 }
+
+// boolEnv reads a flag env var. Anything other than a recognised truthy value
+// is false, so a typo leaves the safe default (migrate here, serve here) rather
+// than silently skipping schema setup.
+func boolEnv(key string) bool {
+	switch strings.ToLower(strings.TrimSpace(os.Getenv(key))) {
+	case "1", "true", "yes", "on":
+		return true
+	}
+	return false
+}

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/api/handlers.go

@@ -20,6 +20,9 @@ func actorFromCtx(c *gin.Context) string {
 }
 
 func RegisterRoutes(r *gin.Engine) {
+	r.GET("/healthz", handleHealthz)
+	r.GET("/readyz", handleReadyz)
+
 	r.GET("/install", handleInstallScript)
 	r.GET("/install.ps1", handleInstallScriptWindows)
 	r.GET("/update", handleUpdateScript)
@@ -139,11 +142,6 @@ func newServer(c *gin.Context) {
 	}
 	services.LogEvent(auth.InstanceID(c), "server.created", actorFromCtx(c), s.ServerID, "", "pre-registration token issued")
 
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
-
 	host := publicHostFromRequest(c)
 
 	installCmd := fmt.Sprintf(
@@ -392,10 +390,7 @@ func applyUpdates(c *gin.Context) {
 }
 
 func handleUpdateScript(c *gin.Context) {
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
+	giteaHost := "gitea.hostxtra.co.uk"
 
 	script := fmt.Sprintf(`#!/usr/bin/env bash
 set -euo pipefail
@@ -419,7 +414,7 @@ if [ -z "$LATEST" ]; then
 fi
 
 VERSION="${LATEST#agent/}"
-LATEST_ENCODED="${LATEST/\
+LATEST_ENCODED="${LATEST/\//%%2F}"
 BINARY_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/vantage-agent-linux-${ARCH}"
 CHECKSUM_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/checksums.txt"
 
@@ -526,7 +521,7 @@ if [ -z "$LATEST" ]; then
 fi
 
 VERSION="${LATEST#agent/}"
-LATEST_ENCODED="${LATEST/\
+LATEST_ENCODED="${LATEST/\//%%2F}"
 BINARY_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/vantage-agent-linux-${ARCH}"
 CHECKSUM_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/checksums.txt"
 

server/internal/api/health.go

@@ -0,0 +1,61 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"time"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/db"
+	"github.com/gin-gonic/gin"
+)
+
+// The two probes answer different questions on purpose.
+//
+// /healthz is liveness: the process is up and serving. It touches nothing
+// external, because a Mongo outage must not make Kubernetes restart every
+// server pod — a restart loop cannot fix someone else's database, and it
+// destroys every open command stream and console session on the way.
+//
+// /readyz is readiness: this pod can serve a request end to end, which needs
+// both Mongo and Redis. A failing readiness probe pulls the pod out of the
+// Service and leaves it running, which is the behaviour that matters during a
+// dependency blip.
+//
+// Both sit outside /api, so neither the session middleware nor the licence
+// gate applies. Neither reveals anything beyond up or down.
+
+const probeTimeout = 2 * time.Second
+
+func handleHealthz(c *gin.Context) {
+	c.JSON(http.StatusOK, gin.H{"status": "ok"})
+}
+
+func handleReadyz(c *gin.Context) {
+	ctx, cancel := context.WithTimeout(c.Request.Context(), probeTimeout)
+	defer cancel()
+
+	checks := gin.H{"mongo": "ok", "redis": "ok"}
+	ready := true
+
+	if db.Client == nil {
+		checks["mongo"] = "not initialised"
+		ready = false
+	} else if err := db.Client.Ping(ctx, nil); err != nil {
+		checks["mongo"] = "unreachable"
+		ready = false
+	}
+
+	if err := auth.PingRedis(ctx); err != nil {
+		checks["redis"] = "unreachable"
+		ready = false
+	}
+
+	status := http.StatusOK
+	state := "ok"
+	if !ready {
+		status = http.StatusServiceUnavailable
+		state = "unready"
+	}
+	c.JSON(status, gin.H{"status": state, "checks": checks})
+}

server/internal/api/install_ps1.go

@@ -12,10 +12,7 @@ func handleInstallScriptWindows(c *gin.Context) {
 	serverID := c.Query("server_id")
 	token := c.Query("token")
 
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
+	giteaHost := "gitea.hostxtra.co.uk"
 
 	grpcHost := os.Getenv("GRPC_HOST")
 
@@ -51,10 +48,7 @@ func handleInstallScriptWindows(c *gin.Context) {
 }
 
 func handleUpdateScriptWindows(c *gin.Context) {
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
+	giteaHost := "gitea.hostxtra.co.uk"
 
 	script := fmt.Sprintf(
 		"#Requires -RunAsAdministrator\n"+

server/internal/api/workflows.go

@@ -1,10 +1,10 @@
 package api
 
 import (
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
-	"os"
 	"regexp"
 	"strconv"
 	"strings"
@@ -49,23 +49,42 @@ func getServerRunLog(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
 		return
 	}
-	path := services.ServerRunLogPath(runID, serverID)
-	b, err := os.ReadFile(path)
-	if err != nil {
+	if !services.HasServerRunLog(runID, serverID) {
 		c.JSON(http.StatusNotFound, gin.H{"error": "no logs"})
 		return
 	}
-	c.Data(http.StatusOK, "text/plain; charset=utf-8", b)
+
+	c.Header("Content-Type", "text/plain; charset=utf-8")
+	c.Status(http.StatusOK)
+
+	// Streamed in pages rather than read whole. A log capped at 200k lines is
+	// tens of megabytes, and holding that in memory per concurrent download is
+	// how one curious user takes a pod down.
+	var after int64
+	for {
+		lines, last, err := services.ReadServerRunLog(runID, serverID, after, logPageSize)
+		if err != nil || len(lines) == 0 {
+			return
+		}
+		for _, l := range lines {
+			_, _ = c.Writer.WriteString(l)
+			_, _ = c.Writer.WriteString("\n")
+		}
+		c.Writer.Flush()
+		after = last
+	}
 }
 
+// logPageSize bounds one read of the log store. Large enough that a normal log
+// is one or two queries, small enough that no single response buffers much.
+const logPageSize = 2000
+
 func streamServerRunLog(c *gin.Context) {
 	runID, serverID := c.Param("runId"), c.Param("serverId")
 	if !uuidLike.MatchString(runID) || !uuidLike.MatchString(serverID) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
 		return
 	}
-	path := services.ServerRunLogPath(runID, serverID)
-
 	c.Writer.Header().Set("Content-Type", "text/event-stream")
 	c.Writer.Header().Set("Cache-Control", "no-cache")
 	c.Writer.Header().Set("Connection", "keep-alive")
@@ -77,29 +96,27 @@ func streamServerRunLog(c *gin.Context) {
 		return
 	}
 
-	var offset int64
+	// The cursor is a sequence number now, not a byte offset: lines come from
+	// the log store, which any pod can read, rather than from a file only this
+	// one has.
+	var after int64
 	sendNew := func() {
-		f, err := os.Open(path)
-		if err != nil {
-			return
-		}
-		defer f.Close()
-		if _, err := f.Seek(offset, 0); err != nil {
-			return
-		}
-		buf := make([]byte, 32*1024)
 		for {
-			n, _ := f.Read(buf)
-			if n <= 0 {
-				break
+			lines, last, err := services.ReadServerRunLog(runID, serverID, after, logPageSize)
+			if err != nil || len(lines) == 0 {
+				return
 			}
-			offset += int64(n)
-
-			for _, line := range splitSSE(buf[:n]) {
-				_, _ = c.Writer.WriteString("data: " + line + "\n")
+			after = last
+			for _, line := range lines {
+				for _, part := range splitSSE([]byte(line)) {
+					_, _ = c.Writer.WriteString("data: " + part + "\n")
+				}
+				_, _ = c.Writer.WriteString("\n")
 			}
-			_, _ = c.Writer.WriteString("\n")
 			flusher.Flush()
+			if len(lines) < logPageSize {
+				return
+			}
 		}
 	}
 
@@ -185,6 +202,10 @@ func updateStep(c *gin.Context) {
 		return
 	}
 	if err := services.UpdateStep(auth.InstanceID(c), c.Param("id"), s); err != nil {
+		if errors.Is(err, services.ErrDefaultStep) {
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
+			return
+		}
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
@@ -194,6 +215,10 @@ func updateStep(c *gin.Context) {
 
 func deleteStep(c *gin.Context) {
 	if err := services.DeleteStep(auth.InstanceID(c), c.Param("id")); err != nil {
+		if errors.Is(err, services.ErrDefaultStep) {
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
+			return
+		}
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}

server/internal/auth/session.go

@@ -5,6 +5,7 @@ import (
 	"crypto/rand"
 	"encoding/hex"
 	"encoding/json"
+	"errors"
 	"time"
 
 	"github.com/redis/go-redis/v9"
@@ -25,13 +26,31 @@ type Session struct {
 
 var rdb *redis.Client
 
-func InitRedis(addr string) error {
-	rdb = redis.NewClient(&redis.Options{Addr: addr})
+// InitRedis connects the session store.
+//
+// Username and password may both be empty for an unauthenticated instance. For
+// a legacy `requirepass` Redis, pass the password with an empty username —
+// go-redis then sends AUTH with one argument instead of two.
+func InitRedis(addr, username, password string) error {
+	rdb = redis.NewClient(&redis.Options{
+		Addr:     addr,
+		Username: username,
+		Password: password,
+	})
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 	return rdb.Ping(ctx).Err()
 }
 
+// PingRedis reports whether the session store is reachable. Readiness depends
+// on it: a pod that cannot reach Redis can authenticate nobody.
+func PingRedis(ctx context.Context) error {
+	if rdb == nil {
+		return errors.New("redis not initialised")
+	}
+	return rdb.Ping(ctx).Err()
+}
+
 func randomHex(n int) (string, error) {
 	b := make([]byte, n)
 	if _, err := rand.Read(b); err != nil {

server/internal/bus/bus.go

@@ -0,0 +1,220 @@
+// Package bus is the control plane's inter-process message bus.
+//
+// It exists because an agent's CommandStream lands on exactly one server
+// process. With a single replica that process is also the one handling every
+// REST request, so an in-memory map was enough. With several replicas it is
+// not: the pod asked to run a workflow step is almost never the pod holding
+// that agent's stream, and a map cannot reach across the gap.
+//
+// Redis is already a hard dependency (sessions), so the bus adds no new
+// infrastructure. It carries three things:
+//
+//	presence  which pod, if any, currently holds an agent's stream
+//	commands  a request/ack exchange delivering a ServerCommand to that pod
+//	results   step results travelling back to the pod driving the run
+//
+// Everything here is deliberately best-effort delivery with an explicit ack
+// rather than a queue. A command whose owner pod died between the presence
+// check and the publish must fail loudly and immediately — the caller answers
+// 503 and the operator retries — not sit in a queue waiting for a stream that
+// no longer exists.
+package bus
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// ErrNoResponder means nothing was subscribed to the channel, or the subscriber
+// did not ack within the timeout. Either way the command did not reach an agent.
+var ErrNoResponder = errors.New("no responder on channel")
+
+var (
+	rdb    *redis.Client
+	nodeID string
+)
+
+// Init connects the bus. It takes its own client rather than sharing the
+// session store's: a subscription occupies its connection for as long as it
+// lives, and every agent stream on this pod holds one, so they must not come
+// out of the pool that ordinary session reads depend on.
+func Init(addr, username, password string) error {
+	rdb = redis.NewClient(&redis.Options{
+		Addr:     addr,
+		Username: username,
+		Password: password,
+	})
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := rdb.Ping(ctx).Err(); err != nil {
+		return err
+	}
+
+	// Hostname is the pod name under Kubernetes, which makes a log line naming
+	// a node directly actionable. The random suffix keeps two processes on one
+	// host (or a reused pod name) from claiming each other's locks.
+	host, _ := os.Hostname()
+	if host == "" {
+		host = "server"
+	}
+	b := make([]byte, 4)
+	_, _ = rand.Read(b)
+	nodeID = host + "-" + hex.EncodeToString(b)
+	return nil
+}
+
+// NodeID identifies this process on the bus. Stable for the process lifetime.
+func NodeID() string { return nodeID }
+
+// Client exposes the underlying Redis client for the leader election and
+// presence helpers in this package. It is nil before Init.
+func Client() *redis.Client { return rdb }
+
+// Channel names. Every key and channel is prefixed so a Redis shared with the
+// session store (which uses km:) stays legible.
+const (
+	prefix = "vantage:"
+
+	// CommandChannel carries envelopes to whichever pod holds serverID's stream.
+	CommandChannel = prefix + "cmd:"
+	// ackChannel carries the owner pod's answer back to the requesting pod.
+	ackChannel = prefix + "ack:"
+	// ResultChannel carries a StepResult back to the pod driving the run.
+	ResultChannel = prefix + "res:"
+	// ProxyEndChannel carries a console relay's terminal reason back to the pod
+	// serving the WebSocket, which is the pod that has to write the audit event.
+	ProxyEndChannel = prefix + "proxyend:"
+
+	// PresenceKey records which node holds an agent's command stream.
+	PresenceKey = prefix + "agent:"
+	// leaderKey records the holder of a named singleton job.
+	leaderKey = prefix + "leader:"
+)
+
+// Publish sends v, JSON-encoded, to channel. It reports how many subscribers
+// received it, which is the only signal Redis pub/sub gives that anyone was
+// listening.
+func Publish(ctx context.Context, channel string, v any) (int64, error) {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return 0, err
+	}
+	return rdb.Publish(ctx, channel, b).Result()
+}
+
+// Subscribe returns a channel of raw payloads and a function that unsubscribes.
+// It blocks until Redis confirms the subscription, so a caller may publish
+// immediately afterwards without racing its own subscriber.
+func Subscribe(ctx context.Context, channel string) (<-chan []byte, func(), error) {
+	ps := rdb.Subscribe(ctx, channel)
+	if _, err := ps.Receive(ctx); err != nil {
+		_ = ps.Close()
+		return nil, nil, err
+	}
+
+	out := make(chan []byte, 64)
+	go func() {
+		defer close(out)
+		for msg := range ps.Channel() {
+			select {
+			case out <- []byte(msg.Payload):
+			default:
+				// A subscriber too slow to keep up would otherwise stall every
+				// other subscriber sharing this connection. Dropping is correct
+				// here: commands are acked, and a dropped ack fails the caller
+				// loudly rather than hanging it.
+			}
+		}
+	}()
+
+	return out, func() { _ = ps.Close() }, nil
+}
+
+// Request publishes req to channel and waits for a single reply on replyTo.
+//
+// The reply subscription is established before the publish, so a responder that
+// answers instantly cannot beat the subscriber into place. A publish that
+// reaches no subscriber fails immediately with ErrNoResponder rather than
+// burning the whole timeout: nobody is going to answer.
+func Request(ctx context.Context, channel, replyTo string, req any, timeout time.Duration) ([]byte, error) {
+	waitCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	replies, unsub, err := Subscribe(waitCtx, replyTo)
+	if err != nil {
+		return nil, fmt.Errorf("subscribe reply channel: %w", err)
+	}
+	defer unsub()
+
+	n, err := Publish(waitCtx, channel, req)
+	if err != nil {
+		return nil, err
+	}
+	if n == 0 {
+		return nil, ErrNoResponder
+	}
+
+	select {
+	case b, ok := <-replies:
+		if !ok {
+			return nil, ErrNoResponder
+		}
+		return b, nil
+	case <-waitCtx.Done():
+		return nil, ErrNoResponder
+	}
+}
+
+// Reply answers a Request on its reply channel.
+func Reply(ctx context.Context, replyTo string, v any) error {
+	_, err := Publish(ctx, replyTo, v)
+	return err
+}
+
+// AckChannelFor names the reply channel for a command. The command ID is
+// already unique per dispatch, so it needs no further qualification.
+func AckChannelFor(commandID string) string { return ackChannel + commandID }
+
+// SetPresence claims serverID for this node for ttl. Called repeatedly by the
+// pod holding the stream; the TTL is what bounds how long a crashed pod keeps
+// claiming an agent it can no longer reach.
+func SetPresence(ctx context.Context, serverID string, ttl time.Duration) error {
+	return rdb.Set(ctx, PresenceKey+serverID, nodeID, ttl).Err()
+}
+
+// ClearPresence releases serverID, but only if this node still holds it. A
+// blind DEL would let a pod whose stream had already been re-established
+// elsewhere delete the new owner's claim on its way out.
+func ClearPresence(ctx context.Context, serverID string) error {
+	return releaseIfOwner.Run(ctx, rdb, []string{PresenceKey + serverID}, nodeID).Err()
+}
+
+// PresenceHolder returns the node holding serverID's stream, or "" if none does.
+func PresenceHolder(ctx context.Context, serverID string) string {
+	v, err := rdb.Get(ctx, PresenceKey+serverID).Result()
+	if err != nil {
+		return ""
+	}
+	return v
+}
+
+// IsConnected reports whether any pod currently holds serverID's stream.
+func IsConnected(ctx context.Context, serverID string) bool {
+	n, err := rdb.Exists(ctx, PresenceKey+serverID).Result()
+	return err == nil && n > 0
+}
+
+var releaseIfOwner = redis.NewScript(`
+if redis.call("GET", KEYS[1]) == ARGV[1] then
+	return redis.call("DEL", KEYS[1])
+end
+return 0
+`)

server/internal/bus/leader.go

@@ -0,0 +1,100 @@
+package bus
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	leaderTTL   = 30 * time.Second
+	leaderRenew = 10 * time.Second
+)
+
+// RunAsLeader runs job on exactly one process at a time, cluster-wide.
+//
+// The background work this guards is not merely wasteful when duplicated. Every
+// replica running the monitor scheduler means every check fires N times, every
+// incident notification is delivered N times to the customer, and every hourly
+// rollup is written N times. The Free-instance reaper is worse: it deletes
+// whole instances, and two processes deleting the same one concurrently is not
+// a race anyone wins.
+//
+// Redis rather than a Kubernetes Lease so that Docker Compose, which has no
+// API server, takes the identical code path — one implementation to reason
+// about, not two.
+//
+// job is given a context cancelled the moment leadership is lost, and must
+// return when it is cancelled. Losing the lock (a paused process, a Redis
+// blip) is treated as fatal to that run of the job: the successor may already
+// have started, and two schedulers overlapping is the exact thing being
+// prevented.
+func RunAsLeader(ctx context.Context, name string, job func(context.Context)) {
+	go func() {
+		key := leaderKey + name
+		for {
+			if ctx.Err() != nil {
+				return
+			}
+			ok, err := rdb.SetNX(ctx, key, nodeID, leaderTTL).Result()
+			if err != nil {
+				log.Printf("leader %s: acquire failed: %v", name, err)
+			}
+			if !ok {
+				select {
+				case <-ctx.Done():
+					return
+				case <-time.After(leaderRenew):
+				}
+				continue
+			}
+
+			log.Printf("leader %s: acquired by %s", name, nodeID)
+			jobCtx, cancel := context.WithCancel(ctx)
+			go job(jobCtx)
+			holdLeadership(ctx, key, name)
+			cancel()
+			log.Printf("leader %s: released by %s", name, nodeID)
+
+			// Give up the key on a clean shutdown so a successor takes over in
+			// milliseconds rather than waiting out the TTL.
+			if ctx.Err() != nil {
+				relCtx, relCancel := context.WithTimeout(context.Background(), 2*time.Second)
+				_ = releaseIfOwner.Run(relCtx, rdb, []string{key}, nodeID).Err()
+				relCancel()
+				return
+			}
+		}
+	}()
+}
+
+// holdLeadership renews the lock until it is lost or ctx ends.
+func holdLeadership(ctx context.Context, key, name string) {
+	t := time.NewTicker(leaderRenew)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			n, err := renewIfOwner.Run(ctx, rdb, []string{key}, nodeID, int(leaderTTL/time.Millisecond)).Int()
+			if err != nil && err != redis.Nil {
+				log.Printf("leader %s: renew failed, standing down: %v", name, err)
+				return
+			}
+			if n == 0 {
+				log.Printf("leader %s: lock lost, standing down", name)
+				return
+			}
+		}
+	}
+}
+
+var renewIfOwner = redis.NewScript(`
+if redis.call("GET", KEYS[1]) == ARGV[1] then
+	return redis.call("PEXPIRE", KEYS[1], ARGV[2])
+end
+return 0
+`)

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/grpc/server.go

@@ -178,8 +178,13 @@ func (s *vantageServer) CommandStream(stream pb.Vantage_CommandStreamServer) err
 		log.Printf("update last seen %s: %v", srv.ServerID, err)
 	}
 
-	ch := services.Dispatcher.Connect(srv.ServerID)
-	defer services.Dispatcher.Disconnect(srv.ServerID)
+	// Serve claims this agent's presence on the bus and subscribes this pod to
+	// its command channel, so a dispatch issued by any other replica arrives
+	// here. The teardown releases both — an agent that reconnects to a
+	// different pod must not leave this one advertising a stream it no longer
+	// has.
+	ch, release := services.Dispatcher.Serve(stream.Context(), srv.ServerID)
+	defer release()
 
 	log.Printf("agent %s connected command stream", srv.ServerID)
 	defer log.Printf("agent %s disconnected command stream", srv.ServerID)

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,273 @@
+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
+	onEnd   func(string)
+
+	rendezvous *time.Timer
+}
+
+// OnEnd registers a callback invoked exactly once, when the session finishes
+// tearing down, with the recorded reason (empty if it ended cleanly).
+//
+// It exists because the process that observes a relay failing is not
+// necessarily the process that has to record it: with several replicas the
+// listener lives on the pod holding the agent's stream, while the audit event
+// belongs to the pod serving the browser's WebSocket.
+func (s *Session) OnEnd(fn func(string)) {
+	s.mu.Lock()
+	s.onEnd = fn
+	s.mu.Unlock()
+}
+
+// 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()
+		}
+
+		// Read after teardown, not before: relay()'s goroutines set the reason
+		// as they unwind, and reporting one recorded earlier than that would
+		// name the symptom rather than the cause.
+		s.mu.Lock()
+		fn, final := s.onEnd, s.reason
+		s.mu.Unlock()
+		if fn != nil {
+			fn(final)
+		}
+	})
+}
+
+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
+}