Frontend

Frontend (protocolsoup-frontend)

Image: ghcr.io/parlesec/protocolsoup-frontend

When To Use

Use frontend when you want the browser UI for flow execution, Looking Glass, and token inspection.

Runtime Contract

Property	Value
Port	3000
Health	Root path GET /
Server	Next.js standalone server (node server.js)
Stack	Next.js App Router, React 18, Tailwind CSS, Framer Motion, Zustand

Dependency

Frontend requires a backend/gateway service reachable at BACKEND_ORIGIN (for example http://gateway:8080 on Docker Compose networks).

The frontend forwards HTTP traffic for these paths to backend: /api, /agentauth, /mcp, /oauth2, /oidc, /oid4vci, /oid4vp, /saml, /spiffe, /scim, /ssf.

Looking Glass also forwards same-origin /wallet-harness/* requests to the wallet harness (WALLET_BACKEND_ORIGIN), with the /wallet-harness prefix removed.

Both origins are read from the container environment on each request, so the published image is pointed at your own backend and wallet with -e; no rebuild is needed. To use a wallet harness you host yourself, see Wallet harness.

WebSocket paths are intentionally not rewritten by Next. Route /ws/* at your edge proxy directly to backend.

Environment

Variable	Required	Default	Purpose
BACKEND_ORIGIN	Yes (outside local defaults)	http://localhost:8080	Backend origin for forwarded HTTP paths. Read at runtime
WALLET_BACKEND_ORIGIN	Yes (for Looking Glass OID4VCI/OID4VP)	(unset)	Wallet harness origin for /wallet-harness/*. Read at runtime. When unset, /wallet-harness/* returns 502 upstream_not_configured instead of falling back to a hosted wallet. WALLET_SITE_URL is used if this is unset
NEXT_PUBLIC_SITE_URL	Yes (production)	https://protocolsoup.com	Canonical public base URL for metadata/sitemaps
DOCS_SITE_URL	No	https://docs.protocolsoup.com	Docs sitemap host for sitemap index

Run

Both containers must be on the same Docker network:

docker network create protocolsoup-net

docker run -d --name gateway --network protocolsoup-net \
  -p 8080:8080 ghcr.io/parlesec/protocolsoup-gateway:latest

docker run -d --name frontend --network protocolsoup-net \
  -e BACKEND_ORIGIN=http://gateway:8080 \
  -e NEXT_PUBLIC_SITE_URL=http://localhost:3000 \
  -p 3000:3000 ghcr.io/parlesec/protocolsoup-frontend:latest

If you use Docker Compose, the docker-compose.yml already configures this networking.

Operational Notes

• If the UI loads but flows fail, verify gateway health at http://localhost:8080/health.
• Verify BACKEND_ORIGIN matches reachable backend host/port from inside the frontend container.
• WebSocket proxying is required for Looking Glass sessions (/ws/lookingglass/{session}) and should bypass the frontend.
• In production, expose only the frontend publicly and keep gateway on an internal network.