Deployment shape¶
Residion runs as a single-host appliance — one VM or one physical server. The full product is a Docker Compose stack of 13 containers (16 with the optional connected/cloud profile).
Not today
There is no multi-node cluster, no HA, and no failover. Databases are single-instance.
Trust rings¶
Three Docker networks on the one host:
| Network | Isolation | Contains |
|---|---|---|
core_net |
internal-only | Data plane: server, client app, operator console, Postgres, Qdrant, Valkey, Keycloak, Langfuse |
dmz_net |
internal-only | The airlock: agent gateway ↔ mTLS proxy |
admin_net |
not internal | Management / host port publishing |
The Agent (DMZ gateway) has no route to core_net. It reaches the Server only through an mTLS nginx proxy, with server-side scope re-derivation.
Surfaces¶
| Surface | Port | Who |
|---|---|---|
| Client App | 18082 | Employees |
| Server Operator Console | 18084 | Customer IT / operators — the console an air-gapped customer needs |
| Agent gateway | 18083 | External channel airlock |
| Cloud Console + Customer Portal | 3000 | Residion-hosted cloud plane — not on the customer box |
LAN reachability
Host ports currently bind via ${RESIDION_HOST:-127.0.0.1} for the four main surfaces; agent gateway, console, and Langfuse remain loopback-pinned in the reference compose. Confirm the binding on your appliance before assuming LAN access from other machines.
Sovereignty properties (architecturally enforced and locally test-proven)¶
These are not certifications or accreditations:
- Structural metadata boundary — the cloud plane has no API path that can accept customer content (content-bearing payloads rejected
422 RES-BOUNDARY-1). - mTLS on both trust rings, including negative tests (no client cert → 400; wrong CA → 400).
- Air-gap zero-egress — verified with an explicit packet-capture filter across all containers.
- RBAC fail-closed, including the vector layer and the SQL path; read-only auditor enforced server-side.
- Keycloak SSO with browser OIDC/PKCE.
How to verify¶
- From the host (or an allowed client), open
http://<host>:18084for the Operator Console. - In Deployment, confirm status and review the install plan. See Deployment.
- Confirm you are not expecting clustering, HA, or a separate DR appliance — those are not in the stack.
If it fails¶
| Symptom | Action |
|---|---|
| Console unreachable on 18084 | Confirm the compose stack is up; confirm bind address (127.0.0.1 vs LAN); use SSH tunnel if loopback-pinned |
| Expecting a second host | Single-host only — see hardware profiles |
| Looking for backup/DR controls | Not available in current software — contact Residion for operational guidance outside the product |