| name | heliosproxy-demo-up |
| description | Bring up any of the 22 v0.4.0 demos under `demos/v0.4.0/<n>/`. Each ships a `demo.sh up\|run\|down` and a self-contained `docker-compose.yml`. Use when the user says "run a demo", "demo.sh", "show me X working", "anomaly detection demo", or asks for a runnable example. |
| allowed-tools | Bash(./demo.sh *), Bash(docker compose *), Bash(cd *), Bash(curl *), Bash(psql *), Read |
| related | ["heliosproxy-overview","heliosproxy-demo-down"] |
Bring up a demo
Every v0.4.0 feature has a runnable demo at
demos/v0.4.0/<NN-name>/. Each demo:
- has a
README.md with the UVP, use cases, walkthrough,
- ships a
docker-compose.yml (proxy + a real PostgreSQL 17 backend),
- and a
demo.sh with up / run / down subcommands.
Default backend is postgres:17-alpine so it works on any laptop
with Docker. Wire-protocol-identical with HeliosDB-Lite — swap the
image: line if you want HeliosDB; demos behave identically.
🟠 Mutating — spins up containers, opens ports.
Prerequisites
- Docker + Docker Compose v2
psql (PostgreSQL 14+ client)curl and jq- For plugin demos: a Rust toolchain with
wasm32-unknown-unknown
target, OR pre-built .wasm artefacts dropped into the
per-demo plugins/ directory.
Demo index
| # | Demo | Module | What it proves |
|---|
| 1 | Anomaly Detection | anomaly-detection | SQLi + auth burst + novel query — three families fire concurrently |
| 2 | Edge / Geo Proxy | edge-proxy | Two proxies (home + edge), invalidation broadcast on write, ~40× cache speedup |
| 3 | Plugin host KV bridge | wasm-plugins | Per-plugin namespaced state survives across hook invocations |
| 4 | Plugin host crypto | wasm-plugins | RFC 6234 SHA-256 vector check + audit-chain producing real digests |
| 5 | Ed25519 signatures | wasm-plugins | openssl-signed .wasm loads; tampered or unsigned refuses |
| 6 | Plugin OCI loader | wasm-plugins | helios-plugin pack → drop tarball → proxy validates SHA-256 |
| 7 | RouteResult::Block | wasm-plugins | Route hook produces clean PG ErrorResponse on rejection |
| 8 | trust_root knob | wasm-plugins | Same proxy binary, different TOML → permissive vs enforced |
| 9 | Admin Web UI | (always-on) | 10-panel dashboard at :9090/, auto-refresh |
| 10 | Admin REST tour | (always-on) | curl tour of all 8 new endpoints |
| 11 | cost-governor | T2.3 | Per-tenant budget exhaustion → block; recovery after window resets |
| 12 | ai-classifier | T2.2 | LLM detection from application_name keywords + generated-by markers |
| 13 | token-budget | T2.2 | Per-(agent, model) cost gate for AI traffic |
| 14 | llm-guardrail | T2.2 | DROP, missing WHERE, missing tenant_id all refused for AI traffic |
| 15 | pgvector-router | T2.2 | Vector top-K → pg-vector replica; non-vector → pg-primary |
| 16 | column-mask | T2.4 | Same query, different roles, masked vs raw PII |
| 17 | audit-chain | T2.4 | Hash-chained tamper-evident log; verify_chain catches mutation |
| 18 | residency-router | T2.4 | EU users → EU replica; US users → US replica; unknown region → block |
| 19 | helios-plugin CLI | (build tool) | Pack/inspect/verify with openssl-generated key |
| 20 | Kubernetes operator | T1.1 | One CR brings up ConfigMap + Deployment + Service; status flips Pending → Ready |
| 21 | Terraform provider | T1.3 | Five resources via main.tf; Terraform-tracked state |
| 22 | Pulumi provider | T1.3 | Same five resources via TypeScript |
Recipes
Recipe 1: Run any demo end-to-end
cd demos/v0.4.0/01-anomaly-detection
./demo.sh
./demo.sh (no arg) defaults to run, which calls up first if
needed. Output streams to your terminal.
Recipe 2: Just bring services up, leave them running
cd demos/v0.4.0/02-edge-proxy
./demo.sh up
docker compose ps
Useful when you want to poke at the running proxy yourself
(curl http://localhost:9090/..., psql -h localhost -p 6432).
See heliosproxy-demo-down to tear down.
Recipe 3: Run the demo against an already-up cluster
cd demos/v0.4.0/01-anomaly-detection
./demo.sh up
./demo.sh run
Most demos are idempotent on run. Anomaly demo's "rate spike"
might saturate the buffer if run many times in quick succession;
restart with down + up to reset state.
Recipe 4: Plugin demos — pre-built wasm vs build-on-demand
The plugin demos (11–18) need the relevant .wasm artefact in
the demo's plugins/ directory. Two options:
Build on demand (requires Rust toolchain + wasm target):
rustup target add wasm32-unknown-unknown
cd demos/v0.4.0/11-cost-governor
./demo.sh up
Pre-built (drop into per-demo plugins/ dir):
cd demos/v0.4.0/11-cost-governor/plugins
cp /path/to/helios_plugin_cost_governor.wasm .
./demo.sh up
The shared bring-up script
demos/v0.4.0/_shared/plugin-demo.sh
handles both paths.
Recipe 5: Demo 9 / 10 — the universal smoke-tests
cd demos/v0.4.0/09-admin-ui && ./demo.sh up
xdg-open http://localhost:9090/
cd demos/v0.4.0/10-admin-rest && ./demo.sh
If you only have time to run two demos, run these. They exercise
every endpoint the other 20 demos use.
Recipe 6: HeliosDB instead of PostgreSQL
Edit the demo's docker-compose.yml:
image: postgres:17-alpine
image: heliosdatabase/heliosdb-lite:latest
The wire protocol is identical; the rest of the demo runs unchanged.
See demos/v0.4.0/_shared/README.md
for the swap recipe.
Pitfalls
- Port conflicts on 6432, 9090, or 5432. Another instance is
bound. Find with
lsof -i :6432. The demo's docker-compose.yml
is the source of port mappings — edit if needed.
docker compose up builds the proxy from a build: context —
in the released demos, the compose files reference
ghcr.io/heliosdatabase/hdb-heliosdb-proxy:0.6.1. If you're testing
an unreleased build, swap image: for build: ../../...- Plugin builds are slow first time. The wasm target downloads
- compiles wasmtime deps. Subsequent demos reuse the cargo cache.
./demo.sh run against a stale up. State accumulates
across runs (cache, journal, anomaly buffer). For a clean state,
./demo.sh down first.- The 09-admin-ui demo serves a real HTML dashboard at the
root of the admin port.
curl http://localhost:9090/ returns
HTML, not JSON. Use /health, /topology, etc. for JSON.
See also
heliosproxy-demo-down — clean tear-downheliosproxy-overview — pick the right skill before running a demodemos/v0.4.0/README.md — top-level indexdemos/v0.4.0/_shared/ — shared scaffolding- Container image:
ghcr.io/heliosdatabase/hdb-heliosdb-proxy:0.6.1
