diff --git a/.github/workflows/voltage-agent-images.yml b/.github/workflows/voltage-agent-images.yml
index 028a729e457..e1c4e70e639 100644
--- a/.github/workflows/voltage-agent-images.yml
+++ b/.github/workflows/voltage-agent-images.yml
@@ -9,11 +9,12 @@ name: Voltage images
# buzz-agent voltage/images/buzz-agent/Dockerfile → voltage-buzz-agent-staging
# buzz-sandbox-reaper voltage/images/buzz-sandbox-reaper/Dockerfile → voltage-buzz-sandbox-reaper-staging
# buzz-relay the upstream root Dockerfile (target runtime) → buzz-relay
+# paseo-relay getpaseo/paseo-relay's Dockerfile at PASEO_RELAY_SOURCE → paseo-relay
# paseo-daemon voltage/images/paseo-daemon/Dockerfile → voltage-paseo-daemon-staging
#
# The changes job selects only the images whose inputs changed. Manual runs
# (workflow_dispatch) build all of them, or only buzz-agent with agent_only.
-# Paseo publishes to staging ECR after provisioning in voltage-terraform #1029.
+# Paseo daemon publishes to staging ECR, provisioned in voltage-terraform #1029.
#
# Trust model: this repository and its logs are public. Pull requests run
# without AWS access. Only the publish and merge jobs request an OIDC token,
@@ -88,6 +89,11 @@ concurrency:
permissions:
contents: read
+env:
+ # The Paseo relay (Apache-2.0), built unmodified from this pinned upstream
+ # commit as a remote BuildKit context. See docs/paseo-relay.md.
+ PASEO_RELAY_SOURCE: https://github.com/getpaseo/paseo-relay.git#5f4b7636af41a85ef20200c0b7e99dd1ea2ee1f2
+
jobs:
changes:
name: Select images
@@ -133,7 +139,7 @@ jobs:
- 'examples/**'
- 'voltage/images/buzz-sandbox-reaper/**'
- '.github/workflows/voltage-agent-images.yml'
- paseo:
+ paseo_daemon:
- '.cargo/**'
- 'Cargo.toml'
- 'Cargo.lock'
@@ -160,6 +166,10 @@ jobs:
- 'web/**'
- 'admin-web/**'
- '.github/workflows/voltage-agent-images.yml'
+ # The source pin lives in this workflow.
+ paseo_relay:
+ - 'voltage/images/test-paseo-relay-image.sh'
+ - '.github/workflows/voltage-agent-images.yml'
- name: Build the image matrices
id: select
env:
@@ -168,20 +178,24 @@ jobs:
AGENT: ${{ steps.filter.outputs.agent }}
REAPER: ${{ steps.filter.outputs.reaper }}
RELAY: ${{ steps.filter.outputs.relay }}
- PASEO: ${{ steps.filter.outputs.paseo }}
+ PASEO_RELAY: ${{ steps.filter.outputs.paseo_relay }}
+ PASEO_DAEMON: ${{ steps.filter.outputs.paseo_daemon }}
run: |
set -euo pipefail
selected=()
if [ "$ALL" = true ] || [ "$AGENT_ONLY" = true ] || [ "$AGENT" = true ]; then selected+=(buzz-agent); fi
if [ "$ALL" = true ] || [ "$REAPER" = true ]; then selected+=(buzz-sandbox-reaper); fi
if [ "$ALL" = true ] || [ "$RELAY" = true ]; then selected+=(buzz-relay); fi
- if [ "$ALL" = true ] || [ "$PASEO" = true ]; then selected+=(paseo-daemon); fi
- images='{
- "buzz-agent": {"file": "voltage/images/buzz-agent/Dockerfile", "target": "", "repository": "voltage-buzz-agent-staging"},
- "buzz-sandbox-reaper": {"file": "voltage/images/buzz-sandbox-reaper/Dockerfile", "target": "", "repository": "voltage-buzz-sandbox-reaper-staging"},
- "buzz-relay": {"file": "Dockerfile", "target": "runtime", "repository": "buzz-relay"},
- "paseo-daemon": {"file": "voltage/images/paseo-daemon/Dockerfile", "target": "", "repository": "voltage-paseo-daemon-staging"}
- }'
+ if [ "$ALL" = true ] || [ "$PASEO_RELAY" = true ]; then selected+=(paseo-relay); fi
+ if [ "$ALL" = true ] || [ "$PASEO_DAEMON" = true ]; then selected+=(paseo-daemon); fi
+ # paseo-relay builds the Dockerfile at the root of its remote context.
+ images=$(jq -cn --arg paseo "$PASEO_RELAY_SOURCE" '{
+ "buzz-agent": {"context": ".", "file": "voltage/images/buzz-agent/Dockerfile", "target": "", "repository": "voltage-buzz-agent-staging"},
+ "buzz-sandbox-reaper": {"context": ".", "file": "voltage/images/buzz-sandbox-reaper/Dockerfile", "target": "", "repository": "voltage-buzz-sandbox-reaper-staging"},
+ "buzz-relay": {"context": ".", "file": "Dockerfile", "target": "runtime", "repository": "buzz-relay"},
+ "paseo-relay": {"context": $paseo, "file": "", "target": "", "repository": "paseo-relay"},
+ "paseo-daemon": {"context": ".", "file": "voltage/images/paseo-daemon/Dockerfile", "target": "", "repository": "voltage-paseo-daemon-staging"}
+ }')
platforms='[{"arch": "amd64", "runner": "ubuntu-latest"}, {"arch": "arm64", "runner": "ubuntu-24.04-arm"}]'
build=$(jq -cn --argjson images "$images" --argjson platforms "$platforms" \
'{include: [$ARGS.positional[] as $image | $platforms[] | {image: $image} + $images[$image] + .]}' \
@@ -206,6 +220,8 @@ jobs:
with:
persist-credentials: false
# The relay's root Dockerfile is upstream's; it gets only BuildKit checks.
+ # The Paseo relay's is checked in its own build and publish jobs instead,
+ # so an unreachable upstream repository fails only that image.
- name: Hadolint buzz-agent
uses: hadolint/hadolint-action@06be81baf89a55ffd0e24b8f04a4185738dd3387 # v3.5.0
with:
@@ -262,10 +278,13 @@ jobs:
# Pull requests never read the internal skills repository.
- name: Empty engineering skills context
run: sh voltage/images/buzz-agent/select-skills.sh --none "$RUNNER_TEMP/engineering-skills"
+ - name: Paseo relay BuildKit check
+ if: matrix.image == 'paseo-relay'
+ run: docker buildx build --check "$PASEO_RELAY_SOURCE"
- name: Build
uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
with:
- context: .
+ context: ${{ matrix.context }}
file: ${{ matrix.file }}
target: ${{ matrix.target }}
platforms: linux/${{ matrix.arch }}
@@ -283,6 +302,10 @@ jobs:
- name: Relay smoke test
if: matrix.image == 'buzz-relay'
run: bash voltage/images/test-relay-image.sh "$IMAGE"
+ - name: Paseo relay smoke test
+ if: matrix.image == 'paseo-relay'
+ run: bash voltage/images/test-paseo-relay-image.sh "$IMAGE"
+
- name: Paseo daemon contract test
if: matrix.image == 'paseo-daemon'
run: bash voltage/images/paseo-daemon/test-image.sh "$IMAGE"
@@ -417,12 +440,15 @@ jobs:
sh voltage/images/buzz-agent/select-skills.sh --none "$out"
fi
echo "revision=$(cat "$out/REVISION")" >> "$GITHUB_OUTPUT"
+ - name: Paseo relay BuildKit check
+ if: matrix.image == 'paseo-relay'
+ run: docker buildx build --check "$PASEO_RELAY_SOURCE"
# Build and smoke-test before credentials exist; the push build below
# reuses this build's cache.
- name: Build
uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
with:
- context: .
+ context: ${{ matrix.context }}
file: ${{ matrix.file }}
target: ${{ matrix.target }}
platforms: linux/${{ matrix.arch }}
@@ -439,6 +465,10 @@ jobs:
- name: Relay smoke test
if: matrix.image == 'buzz-relay'
run: bash voltage/images/test-relay-image.sh "$IMAGE"
+ - name: Paseo relay smoke test
+ if: matrix.image == 'paseo-relay'
+ run: bash voltage/images/test-paseo-relay-image.sh "$IMAGE"
+
- name: Paseo daemon contract test
if: matrix.image == 'paseo-daemon'
run: bash voltage/images/paseo-daemon/test-image.sh "$IMAGE"
@@ -458,7 +488,7 @@ jobs:
id: push
uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
with:
- context: .
+ context: ${{ matrix.context }}
file: ${{ matrix.file }}
target: ${{ matrix.target }}
platforms: linux/${{ matrix.arch }}
diff --git a/docs/paseo-relay.md b/docs/paseo-relay.md
new file mode 100644
index 00000000000..763da78098f
--- /dev/null
+++ b/docs/paseo-relay.md
@@ -0,0 +1,129 @@
+# Paseo relay
+
+Voltage runs its own [Paseo relay](https://github.com/getpaseo/paseo-relay) at `wss://buzz.voltage.cloud/ws`.
+Paseo apps ([paseo.sh](https://paseo.sh)) use it to reach a developer's Paseo daemon, which fronts that developer's Buzz remote agents.
+The app and the daemon both connect out to the relay, so neither one needs an open inbound port.
+
+The Paseo relay is a separate service. The Buzz relay does not know about Paseo, and Paseo traffic never enters the Buzz Nostr relay.
+This repository only builds the image. The deployment is in voltagecloud/cd (`charts/paseo-relay`, `prod/apps/paseo-relay`).
+
+## What runs
+
+| Item | Value |
+| --- | --- |
+| Source | [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay) (Apache-2.0, Elixir/OTP), unmodified |
+| Pinned commit | `5f4b7636af41a85ef20200c0b7e99dd1ea2ee1f2`, in `PASEO_RELAY_SOURCE` of [`voltage-agent-images.yml`](../.github/workflows/voltage-agent-images.yml) |
+| Image | Prod ECR repository `paseo-relay`, tagged with the voltagecloud/buzz commit, pinned by digest in voltagecloud/cd |
+| Workload | One pod in the prod EKS cluster, namespace `buzz`, Argo CD Application `paseo-relay` |
+| State | None on disk. Sessions live in the memory of the one BEAM node. |
+| Secrets | None |
+
+The relay forwards frames that are end-to-end encrypted between the app and the daemon.
+It reads only the routing query parameters and the public key in `hello` and `e2ee_hello` frames.
+
+## Routing
+
+The relay shares the `buzz.voltage.cloud` hostname and the public Traefik `secure` entrypoint with the Buzz relay.
+Traefik selects the backend by path. No DNS record is added.
+
+```mermaid
+flowchart LR
+ app[Paseo app] -- "wss :443 /ws" --> traefik
+ daemon[Paseo daemon] -- "wss :443 /ws" --> traefik
+ desktop[Buzz clients] -- "wss :443 /" --> traefik
+ traefik[Traefik secure entrypoint
buzz.voltage.cloud] -- "Path /ws, priority 90
64 in-flight per client IP" --> paseo[paseo-relay:4000]
+ traefik -- "Path /pair, priority 90" --> pairing[buzz-pairing:5000]
+ traefik -- "all other paths" --> buzz[buzz:3000]
+```
+
+| Rule | Owner | Middleware |
+| --- | --- | --- |
+| `Host(buzz.voltage.cloud) && Path(/ws)` | voltagecloud/cd `charts/paseo-relay` IngressRoute | `paseo-relay-inflight-limit` |
+| `Host(buzz.voltage.cloud) && Path(/pair)` | Buzz IngressRoute in `prod/values/buzz/prod.yaml` | `pairing-inflight-limit` |
+| `Host(buzz.voltage.cloud)` | Buzz IngressRoute | none |
+
+The Buzz relay does not serve `/ws`. It accepts WebSockets on `/`, and `/ws` matches none of its routes, so it returns 404.
+TLS terminates at Traefik. Clients always use `wss` on port 443; the relay never accepts plain `ws` from outside the cluster.
+`/health`, `/ready`, and `/metrics` listen on the same port 4000 but have no public route.
+
+## Connections
+
+Every socket uses the path `/ws` and these query parameters:
+
+```text
+/ws?serverId=&role=server&v=2 daemon control socket
+/ws?serverId=&role=client&v=2&connectionId= app socket
+/ws?serverId=&role=server&v=2&connectionId= daemon data socket for one app
+```
+
+The relay sends the control socket a `sync` message, and a `connected` message when an app arrives.
+The daemon then opens one data socket for that `connectionId`.
+`serverId` and `connectionId` are limited to 256 bytes.
+
+## Point a daemon at the relay
+
+Set these variables in the Paseo daemon's environment:
+
+| Variable | Value |
+| --- | --- |
+| `PASEO_RELAY_ENABLED` | `true`, unless the daemon config already enables the relay. New daemon homes start with the relay off. |
+| `PASEO_RELAY_ENDPOINT` | `buzz.voltage.cloud:443` |
+| `PASEO_RELAY_PUBLIC_ENDPOINT` | `buzz.voltage.cloud:443` |
+| `PASEO_RELAY_USE_TLS` | `true` |
+| `PASEO_RELAY_PUBLIC_USE_TLS` | `true` |
+
+The daemon connects to `PASEO_RELAY_ENDPOINT`. It gives `PASEO_RELAY_PUBLIC_ENDPOINT` to the apps it pairs with, so both values are the same public address.
+Without these variables, the daemon uses Paseo's hosted relay, `relay.paseo.sh:443`.
+Do not set the TLS variables to `false`: Traefik routes `/ws` only on its TLS entrypoint.
+
+## Relay settings
+
+The cd chart sets these values. The upstream [runtime contract](https://github.com/getpaseo/paseo-relay#runtime-contract) lists every setting.
+
+| Setting | Prod value | Reason |
+| --- | --- | --- |
+| `PASEO_RELAY_HOST`, `PASEO_RELAY_PORT` | `0.0.0.0`, `4000` | Listen on the pod IP. |
+| `RELEASE_DISTRIBUTION` | `none` | The release otherwise starts EPMD and a distribution port on all interfaces, protected only by a cookie that is readable in the image. |
+| `RELEASE_COOKIE` | not set | Not used without distribution. |
+| `PASEO_RELAY_MEMORY_WATERMARK_BYTES` | `805306368` (768 MiB) | Shed sockets with close code `1013` before the 1 GiB memory limit. |
+| `PASEO_RELAY_INGRESS_BUDGET_BYTES` | `268435456` (256 MiB) | Two 32 MiB messages at weight 4. |
+| `PASEO_RELAY_CONNECTIONS_PER_ACCEPTOR` | `40` | 4,000 sockets. An idle socket and its session measured about 125 KiB. |
+| `LANG` | `C.UTF-8` | The VM expects UTF-8 file names. |
+| `ERL_CRASH_DUMP_SECONDS` | `0` | The root filesystem is read-only. |
+
+The pod runs as UID 65532 with a read-only root filesystem, all capabilities dropped, and the `RuntimeDefault` seccomp profile.
+Resources: requests 100m CPU and 256 MiB, limits 1 CPU and 1 GiB.
+Prometheus scrapes `/metrics` through a ServiceMonitor. `paseo_relay_ready`, `paseo_relay_active_websockets`, and `paseo_relay_beam_total_memory_bytes` show health and load.
+
+## Limits
+
+- **No Buzz gating.** Any client that reaches `/ws` can register any `serverId`, as on Paseo's hosted relay. The relay does not check Buzz membership. End-to-end encryption and the daemon password protect the sessions.
+- **One replica.** A restart or rollout drops every session for a few seconds, and apps and daemons reconnect. More replicas need BEAM clustering and an adapter that reroutes upgrades to the owning node.
+- **Shared in-flight budget.** Traefik allows 64 concurrent requests per client IP and returns 429 above that. Daemons behind one egress IP, such as the single staging NAT gateway, share the budget. Raise `ingressRoute.inFlightPerClientIp` in voltagecloud/cd when more daemons share an IP.
+- **Pod-wide ceiling.** At 4,000 sockets or under memory pressure, `/ready` returns 503 and new connections fail until load drops.
+
+## Build and test the image
+
+[`voltage-agent-images.yml`](../.github/workflows/voltage-agent-images.yml) builds `PASEO_RELAY_SOURCE` as a remote BuildKit context, with the upstream `Dockerfile` unchanged.
+Pull requests build `linux/amd64` and `linux/arm64` without a push. `main` pushes both and merges them into one manifest list.
+[`test-paseo-relay-image.sh`](../voltage/images/test-paseo-relay-image.sh) runs the image with the prod hardening and limits.
+The test checks `/health`, `/ready`, `/metrics`, a `101` upgrade on `/ws`, UID 65532, and that port 4000 is the only TCP listener.
+
+```bash
+docker buildx build --check "https://github.com/getpaseo/paseo-relay.git#5f4b7636af41a85ef20200c0b7e99dd1ea2ee1f2"
+docker build -t paseo-relay:local "https://github.com/getpaseo/paseo-relay.git#5f4b7636af41a85ef20200c0b7e99dd1ea2ee1f2"
+bash voltage/images/test-paseo-relay-image.sh paseo-relay:local
+```
+
+Expected last line:
+
+```text
+paseo relay image paseo-relay:local passed
+```
+
+## Upgrade the relay
+
+1. Read the upstream commits and the runtime contract since the pinned commit. Note new or changed settings.
+2. Change the commit in `PASEO_RELAY_SOURCE`, here and in this document, and open a pull request.
+3. After the merge, copy the `paseo-relay` digest from the `main` run's job summary.
+4. In voltagecloud/cd, pin the digest in `prod/values/paseo-relay/prod.yaml` and sync `paseo-relay` manually. See `prod/apps/paseo-relay/README.md`.
diff --git a/voltage/images/README.md b/voltage/images/README.md
index c1f06291dfe..412d4e56eef 100644
--- a/voltage/images/README.md
+++ b/voltage/images/README.md
@@ -5,16 +5,18 @@ To set up and use remote agents, see [Run Buzz agents in staging Sandboxes](../r
It is Voltage-only, so upstream block/buzz syncs do not conflict with it.
The agent images moved here from voltagecloud/images at `f944157`.
The same workflow also builds the Buzz relay image from the upstream root `Dockerfile`; see [The relay image](#the-relay-image).
+It also builds the Paseo relay image from a pinned upstream commit; see [The Paseo relay image](#the-paseo-relay-image).
| Image | Contents | ECR repository |
| --- | --- | --- |
| [buzz-agent](buzz-agent/README.md) | Remote developer agent Sandbox: the `sprig` harness, Codex and Claude ACP adapters, and developer tools. It also runs as the `buzz-agent-gate` DaemonSet. | `voltage-buzz-agent-staging` |
| [buzz-sandbox-reaper](buzz-sandbox-reaper/Dockerfile) | In-cluster reaper for ended and orphaned agent Sandboxes (`buzz-sandbox-reaper reconcile`) | `voltage-buzz-sandbox-reaper-staging` |
| [buzz-relay](#the-relay-image) | Buzz relay, admin, and pair relay binaries with the web bundles, from the root `Dockerfile` | `buzz-relay` |
+| [paseo-relay](#the-paseo-relay-image) | The Paseo relay, from the upstream `Dockerfile` of getpaseo/paseo-relay at `PASEO_RELAY_SOURCE` | `paseo-relay` |
| [paseo-daemon](paseo-daemon/README.md) | Paseo daemon that runs a developer's personal assistant in front of Buzz remote agents | `voltage-paseo-daemon-staging` |
-Each image compiles the Buzz crates of the commit it is built from.
-The build context is the repository root.
+Each Buzz image compiles the Buzz crates of the commit it is built from.
+The build context is the repository root, except for `paseo-relay`.
For the agent images and `paseo-daemon`, BuildKit reads the `Dockerfile.dockerignore` next to each Dockerfile instead of the root `.dockerignore`.
These files keep only the Cargo workspace and the files that each Dockerfile copies from its own directory.
@@ -24,7 +26,7 @@ These files keep only the Cargo workspace and the files that each Dockerfile cop
Its first job selects only the images whose inputs changed; manual runs build all of them.
- Pull requests: hadolint and BuildKit checks, then a build of each selected image for `linux/amd64` and `linux/arm64` on native runners, without a push.
- The workflow tests the agent image on both platforms, runs the reaper binary, smoke-tests the relay image with [`test-relay-image.sh`](test-relay-image.sh), and runs [`paseo-daemon/test-image.sh`](paseo-daemon/test-image.sh).
+ The workflow tests the agent image on both platforms, runs the reaper binary, smoke-tests the relay images with [`test-relay-image.sh`](test-relay-image.sh) and [`test-paseo-relay-image.sh`](test-paseo-relay-image.sh), and runs [`paseo-daemon/test-image.sh`](paseo-daemon/test-image.sh).
These jobs have no AWS access.
- `main`: each platform builds on its native runner and is pushed by digest.
A merge job then creates one manifest list per image, tagged with the full commit SHA.
@@ -32,9 +34,9 @@ Its first job selects only the images whose inputs changed; manual runs build al
The job summary lists the manifest list digest for each image.
- Manual runs (`workflow_dispatch`) publish only on `main`.
-The voltage-terraform `v2/environments/staging` root creates the two agent ECR repositories; `v2/environments/prod` creates `buzz-relay`.
+The voltage-terraform `v2/environments/staging` root creates the two agent ECR repositories; `v2/environments/prod` creates `buzz-relay` and `paseo-relay`.
Publishing assumes the `github-buzz-ecr-push` IAM role (voltage-terraform `v2/environments/github`).
-The role trusts only `repo:voltagecloud/buzz:ref:refs/heads/main` and can push to and read only these three repositories.
+The role trusts only `repo:voltagecloud/buzz:ref:refs/heads/main` and can push to and read only these four repositories.
The repository secret `AWS_ACCOUNT_ID` supplies the account ID, so the account ID is not in the repository and is masked in the public logs.
## Deploying a digest
@@ -46,6 +48,7 @@ Pin the manifest list digest from the job summary (`@sha256:
| `voltage-buzz-agent-staging` | The Buzz Kubernetes provider `image`, and `image.digest` in voltagecloud/cd `staging/values/infra-utils/buzz-agent-gate.yaml` |
| `voltage-buzz-sandbox-reaper-staging` | `image.digest` in voltagecloud/cd `staging/values/infra-utils/buzz-sandbox-reaper.yaml` |
| `buzz-relay` | `image.repository` and `image.digest` in voltagecloud/cd `prod/values/buzz/prod.yaml` |
+| `paseo-relay` | `image.digest` in voltagecloud/cd `prod/values/paseo-relay/prod.yaml` |
The voltage-terraform admission policy admits only digest-pinned images from `voltage-buzz-agent-staging` in developer namespaces.
@@ -81,3 +84,17 @@ docker buildx build --check .
docker build --platform linux/amd64 --target runtime -t buzz-relay:local .
bash voltage/images/test-relay-image.sh buzz-relay:local
```
+
+## The Paseo relay image
+
+The Paseo relay image is [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay) (Apache-2.0), built from its own `Dockerfile` without changes.
+The workflow pins the upstream commit in `PASEO_RELAY_SOURCE` and builds that URL as a remote BuildKit context.
+It tags the image with the voltagecloud/buzz commit; the workflow file at that commit records the upstream commit.
+[`test-paseo-relay-image.sh`](test-paseo-relay-image.sh) runs the image with the production hardening and limits.
+See [Paseo relay](../../docs/paseo-relay.md) for routing, settings, and upgrades.
+
+```bash
+docker buildx build --check "https://github.com/getpaseo/paseo-relay.git#5f4b7636af41a85ef20200c0b7e99dd1ea2ee1f2"
+docker build -t paseo-relay:local "https://github.com/getpaseo/paseo-relay.git#5f4b7636af41a85ef20200c0b7e99dd1ea2ee1f2"
+bash voltage/images/test-paseo-relay-image.sh paseo-relay:local
+```
diff --git a/voltage/images/test-paseo-relay-image.sh b/voltage/images/test-paseo-relay-image.sh
new file mode 100755
index 00000000000..aadcd00117b
--- /dev/null
+++ b/voltage/images/test-paseo-relay-image.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Smoke-test a Paseo relay image the way production runs it (voltagecloud/cd
+# charts/paseo-relay): non-root, read-only root filesystem, no capabilities,
+# no Erlang distribution, and the prod memory and socket limits. The relay
+# must answer its probes, upgrade a daemon socket on /ws, and listen on no
+# port other than 4000.
+set -euo pipefail
+
+image=${1:?usage: test-paseo-relay-image.sh }
+name="paseo-relay-smoke-$$"
+
+cleanup() {
+ docker rm --force "$name" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+docker run --detach --name "$name" \
+ --read-only --user 65532:65532 --cap-drop ALL --security-opt no-new-privileges \
+ --memory 1g --cpus 1 \
+ --env PASEO_RELAY_HOST=0.0.0.0 \
+ --env PASEO_RELAY_PORT=4000 \
+ --env RELEASE_DISTRIBUTION=none \
+ --env LANG=C.UTF-8 \
+ --env ERL_CRASH_DUMP_SECONDS=0 \
+ --env PASEO_RELAY_MEMORY_WATERMARK_BYTES=805306368 \
+ --env PASEO_RELAY_INGRESS_BUDGET_BYTES=268435456 \
+ --env PASEO_RELAY_CONNECTIONS_PER_ACCEPTOR=40 \
+ --publish 127.0.0.1::4000 "$image" >/dev/null
+
+base="http://$(docker port "$name" 4000/tcp | head -n 1)"
+
+for _ in $(seq 1 100); do
+ if curl --fail --silent "$base/health" >/dev/null 2>&1; then
+ break
+ fi
+ sleep 0.2
+done
+
+if ! curl --fail --silent "$base/health" >/dev/null 2>&1; then
+ docker logs "$name" >&2
+ echo "the relay did not start" >&2
+ exit 1
+fi
+
+test "$(curl --fail --silent --show-error "$base/health")" = '{"status":"ok"}'
+test "$(curl --fail --silent --show-error "$base/ready")" = '{"status":"ready"}'
+curl --fail --silent --show-error "$base/metrics" | grep --quiet '^paseo_relay_ready 1$'
+
+# A daemon control socket upgrades. curl then waits on the open socket until
+# --max-time, so its exit status is ignored; the status code is what counts.
+status=$(curl --silent --output /dev/null --write-out '%{http_code}' --max-time 3 \
+ --header 'Connection: Upgrade' \
+ --header 'Upgrade: websocket' \
+ --header 'Sec-WebSocket-Version: 13' \
+ --header 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
+ "$base/ws?serverId=smoke&role=server&v=2" || true)
+if [ "$status" != 101 ]; then
+ echo "expected 101 from /ws, got $status" >&2
+ exit 1
+fi
+
+# Only 0.0.0.0:4000 (0FA0) listens: no EPMD (4369) or distribution port.
+listeners=$(docker exec "$name" sh -c \
+ 'awk "NR > 1 && \$4 == \"0A\" { print \$2 }" /proc/net/tcp /proc/net/tcp6 2>/dev/null' | sort -u)
+if [ "$listeners" != "00000000:0FA0" ]; then
+ echo "unexpected TCP listeners: $listeners" >&2
+ exit 1
+fi
+
+test "$(docker exec "$name" id -u)" = 65532
+
+echo "paseo relay image $image passed"