| name | heliosproxy-overview |
| description | Top-level navigation for HeliosProxy. Auto-loads when the user mentions "heliosproxy", "helios proxy", or pastes its admin REST output / config / log lines. Routes to one of 21 domain skills (install, start, config, shutdown, connect, topology, health, chaos, switchover, time-travel, shadow-execute, anomaly, plugin-{pack,load,kv,catalog}, edge, demo-{up,down}, release, iac). Use this skill to find the right skill before going deep. |
| allowed-tools | Bash(curl *), Bash(psql *), Read, Grep, Glob |
| related | ["heliosproxy-install","heliosproxy-start","heliosproxy-config"] |
HeliosProxy — Operational Overview
When to use
Any task involving HeliosProxy. This skill is the index — it answers
"which skill should I read?" and gives a one-shot orientation.
After picking a domain skill, follow that skill's recipes.
🔵 Read-only (just navigation)
What is HeliosProxy
PostgreSQL-wire-protocol-compatible connection router and intelligent
query proxy. Sits between an application and a PG-compatible cluster
(PostgreSQL ≥12, HeliosDB, CockroachDB, YugabyteDB, AlloyDB,
TimescaleDB, Citus). Crate name: heliosdb-proxy. Binary name:
heliosdb-proxy. Repo: HeliosDatabase/HDB-HeliosDB-Proxy. Default
listen ports: PG 6432, admin 9090.
24+ feature-gated modules including pool modes (Session/Transaction/
Statement), HA + Transaction Replay, multi-tier query cache,
multi-tenancy, WASM plugins, GraphQL gateway, schema-aware routing,
DistribCache, anomaly detection, edge/geo proxy.
Pick a skill
| If the task is about… | Read |
|---|
| Installing the binary, building from source, picking feature flags | heliosproxy-install |
| Daemonizing, CLI flags, env vars, systemd | heliosproxy-start |
proxy.toml syntax, nodes block, feature blocks, TLS | heliosproxy-config |
| SIGTERM, drain semantics, observing shutdown | heliosproxy-shutdown |
psql round-trip, route hints, sanity-check the proxy | heliosproxy-connect |
/topology, /nodes, current primary, enable/disable nodes | heliosproxy-topology |
/health, /metrics, /sessions, /pools, /version, alerting | heliosproxy-health |
| Chaos: force_unhealthy, restore, reset, watch failover | heliosproxy-chaos |
| Switchover/failover semantics, promotion, primary-tracker | heliosproxy-switchover |
Replay journal window onto staging (POST /api/replay) | heliosproxy-time-travel |
Dual-execute + diff (POST /api/shadow), PG-upgrade validation | heliosproxy-shadow-execute |
GET /anomalies: SQL-injection / auth-burst / rate-spike / novel-query | heliosproxy-anomaly |
helios-plugin pack/inspect/verify, OCI artefacts, Ed25519 sigs | heliosproxy-plugin-pack |
Loading a .wasm plugin, hot-reload, trust-root, /plugins | heliosproxy-plugin-load |
/admin/kv/<plugin>/<key>: per-plugin runtime config | heliosproxy-plugin-kv |
| First-party plugins (cost-governor / ai-classifier / token-budget / llm-guardrail / pgvector-router / column-mask / audit-chain / residency-router) | heliosproxy-plugin-catalog |
Edge mode, /api/edge/{register,invalidate}, last-write-wins TTL | heliosproxy-edge |
demos/v0.4.0/<n>/demo.sh up, picking a demo to run | heliosproxy-demo-up |
demo.sh down, port-conflict, volume cleanup | heliosproxy-demo-down |
| Cutting a release: bump → tag → push → workflow | heliosproxy-release |
| K8s operator + CRD, Terraform provider, Pulumi provider | heliosproxy-iac |
Sanity-check the install (one-liners)
heliosdb-proxy --version
curl -s http://localhost:9090/health
curl -s http://localhost:9090/topology | jq .
If --version fails: see heliosproxy-install.
If /health returns nothing: see heliosproxy-start.
If /topology shows currentPrimary: null: see heliosproxy-topology
(it's normal during failover; after — read heliosproxy-switchover).
Map of operational verbs
See _index/verb-map.md for a full
verb → skill table. See _index/feature-matrix.md
for which feature flags unlock which skills.
When in doubt
The 22 demos under demos/v0.4.0/ are runnable end-to-end on any
laptop with Docker + Compose. They're the fastest way to see a feature
work before reading the corresponding skill.
cd demos/v0.4.0/10-admin-rest && ./demo.sh
cd demos/v0.4.0/01-anomaly-detection && ./demo.sh
cd demos/v0.4.0/02-edge-proxy && ./demo.sh
See heliosproxy-demo-up for the full demo index.
See also
heliosproxy-install — start here on a fresh machineheliosproxy-start — start here on a running buildREADME.md — repo-level overviewCHANGELOG.md — release notesdocs/ — design docs and RFCs
