Agata Proxima

Security infrastructure for multi-tenant PostgreSQL applications.

Proxima Engine is a Rust PostgreSQL-protocol gateway that verifies signed tenant context and routes each database session to its tenant-specific PostgreSQL role.

Continuous integration · MIT license for covered Engine source · Website · Discord · X · LinkedIn

Start: What is Agata Proxima? · Customer Docker install · Guided customer install (Windows/Linux) · Deployment executor · Launch evaluation · Quickstart · Local developer mode · Engine CLI · Documentation index

Technical guides: Architecture · Tenant isolation · Driver integrations · API and metrics · Security · Deployment · Verification

Watch: Zero-Trust Tenant Isolation in Action

Proxima Engine enforces tenant identity at the PostgreSQL proxy boundary. This recorded engineering demonstration shows the Engine under real database and connection-pooling conditions.

The walkthrough covers PgBouncer transaction pooling, deliberately misconfigured Row-Level Security scenarios, 1,000 distinct tenant identities with up to 50 concurrent clients, signed-token validation, and Engine recovery.

Watch the full demonstration:

Demo_under10MB.mp4

Read the engineering case study: Tenant isolation, PgBouncer pooling, 1,000-identity validation, RLS scenarios, and Engine recovery · Recorded validation evidence

---

What is Agata Proxima?

Agata Proxima provides security infrastructure for applications that serve multiple customers from a shared PostgreSQL environment. Its core job is to make tenant identity part of the database connection boundary and route each verified tenant session to a dedicated PostgreSQL role.

The product has two cooperating components:

Proxima Engine — public, open-source data plane

Proxima Engine is a Rust service that sits between an application's existing PostgreSQL driver and PostgreSQL. It speaks the PostgreSQL wire protocol, so applications keep their existing database drivers and connect to the Engine endpoint.

The Engine provides:

• Signed tenant-context verification. Validates tenant tokens using HMAC-SHA256, including token format, tenant identifier, expiry, and signature. Missing or invalid context is rejected when tenant enforcement is enabled.
• Tenant-to-role routing. Maps the verified tenant identity to a configured PostgreSQL role and establishes a tenant-bound upstream database session.
• PostgreSQL-native enforcement. Works with database roles, grants, and Row-Level Security (RLS), keeping data authorization inside PostgreSQL.
• Protocol and connection controls. Handles PostgreSQL startup and authentication negotiation, connection limits, upstream timeouts, and configurable client/upstream TLS.
• Security operations. Includes a peer-scoped violation breaker, short-lived break-glass tokens with replay protection, and a local signed attestation ledger.
• Operational visibility. Exposes local health and status routes plus Prometheus metrics.
• Developer tooling. Includes a Python standard-library CLI, local identity bootstrap, tenant-token generation, integration examples, and repeatable PostgreSQL tests.

Agata Proxima Cloud — hosted management product

Agata Proxima Cloud is the separate hosted control plane for organization workflows, teams, plans, billing, registered nodes, and hosted management. It coordinates authorized Engine nodes while database traffic remains in the customer environment.

The Cloud application and its private source are separate from this public Engine repository. The MIT license in this repository applies to the material covered by its license; it does not grant access to the hosted application's source code or hosted account features.

How the request path works

flowchart LR
  App["Application + existing PostgreSQL driver"] -->|"PostgreSQL protocol + signed tenant context"| Engine["Proxima Engine · Rust"]
  Engine -->|"Tenant-specific PostgreSQL role"| Pool["PgBouncer transaction pool (optional)"]
  Pool --> PG[("PostgreSQL · grants + RLS")]
  Engine --> Health["Health / status"]
  Engine --> Metrics["Prometheus metrics"]
  Cloud["Agata Proxima Cloud · hosted control plane"] -.->|"Authorized enrollment and management"| Engine

Loading

Proxima Engine extends an existing PostgreSQL deployment: it verifies tenant context and selects the database role, while PostgreSQL privileges and RLS policies enforce which rows that role can read or modify. Application authentication and tenant authorization remain in the trusted application backend that issues signed tenant tokens.

Get started

Requirements: Git and Docker with Compose.

git clone https://github.com/Agata-Proxima/proxima-engine.git
cd proxima-engine
docker compose -f compose.dev.yaml up --build -d

The local profile starts PostgreSQL, PgBouncer in transaction-pooling mode, and Proxima Engine. Check the local listeners:

curl -fsS http://127.0.0.1:9090/healthz
curl -fsS http://127.0.0.1:9080/api/status

Windows PowerShell:

Invoke-RestMethod http://127.0.0.1:9090/healthz
Invoke-RestMethod http://127.0.0.1:9080/api/status

Then follow the Quickstart to create a table, send a real SQL query through the Engine and PgBouncer, inspect metrics, and stop the local stack. The Compose profile uses disposable local credentials and synthetic data.

Verify tenant isolation

The repository includes PostgreSQL-backed tenant tests and a dedicated PgBouncer tenant-pool integration test, which is run by GitHub Actions.

The verification path covers:

1. Tenant A authenticates and reads only Tenant A's row.
2. Tenant B authenticates and reads only Tenant B's row.
3. Cross-tenant reads return zero visible rows.
4. Cross-tenant writes are rejected by PostgreSQL RLS.
5. Missing or invalid signed tenant context is rejected when enforcement is enabled.
6. Five sequential connections per tenant reuse that tenant role's backend PID, while the two tenant roles use separate backend PIDs through PgBouncer transaction pooling.

See Tenant isolation, Verification, and the recorded PgBouncer transaction-pooling evidence.

Documentation

Guide	Purpose
Quickstart	Start the local stack and query PostgreSQL through the Engine
Local developer mode	Generate local node identity and signed tenant test tokens
Engine CLI	Bootstrap, token generation, diagnostics, and local status commands
Architecture	Request lifecycle, tenant context, source map, and control-plane boundary
Configuration	Environment variables, defaults, and validation
Tenant isolation	PostgreSQL roles, RLS policies, signed context, and test results
Driver integrations	psql, Node.js, Python, and Rust connection examples
API reference	PostgreSQL endpoint, health/status routes, and Prometheus metrics
Node enrollment	Customer Docker installation, one-time enrollment, signed heartbeat, and identity persistence
Customer deployment executor	Install and operate the customer-managed, signed Docker Compose deployment executor
Deployment	Container build, TLS, networking, persistence, and deployment configuration
Operations	Health checks, logs, monitoring, recovery, and troubleshooting
Engineering case study	Executed tenant-isolation, RLS, PgBouncer, concurrency, authentication, and recovery results
Verification	Rust tests, PostgreSQL integration tests, CI, and evidence verification
Security model	Implemented controls and the configuration required to operate them
Developer security walkthrough	Reproduce positive and negative tenant-access scenarios
Cloud control plane	Hosted product and self-managed Engine responsibilities
Plans and billing	Hosted plan and checkout information
Support	Technical support, issue reporting, and contact routes
Contributing	Development setup and pull-request process
Security policy	Private vulnerability reporting
Code of Conduct	Community participation standards
Copyright and brand	Source-license and brand-asset boundaries
Open-source scope	MIT-licensed source, self-managed use, and support boundaries

Hosted product and contact

• Website and hosted account: agataproxima.com
• Plans and billing: Hosted plan information
• Support: support@agataproxima.com
• Security reports: Private vulnerability reporting instructions
• Community: Discord

Open-source scope

The Proxima Engine source and covered documentation are distributed under the MIT License. The hosted Cloud application, hosted account workflows, and private management source are separate products and are not included in this repository's license. The Agata Proxima name, orbit logo, and designated brand artwork are reserved brand assets; see Copyright and brand.

Contribute

Use GitHub Issues for reproducible Engine bugs and feature requests. Read Contributing before submitting a pull request. For vulnerabilities, use the private reporting process in SECURITY.md.

Built by Agata Proxima · agataproxima.com · GitHub organization

Install a registered Engine node on Windows or Linux

The customer-node installer supports Windows 10/11 hosts running Docker Desktop with the WSL 2 backend, Linux containers, and Docker Compose v2. Windows users have a dedicated PowerShell installer; Linux users have a Bash installer. Both install the same Proxima Engine container and use the same signed enrollment and heartbeat protocol.

Windows downloads

1. Download the Proxima Engine source ZIP and extract it.
2. In Agata Proxima Cloud → Nodes, copy the Windows PowerShell setup commands shown with the node's one-time enrollment token.
3. Keep the included Windows PowerShell installer and customer Compose file together in the extracted repository folder.
4. Paste the copied setup commands into the same PowerShell session. The installer generates .env and secrets/node_enrollment_token; it prompts for the PostgreSQL upstream address if it is not set. No tenant signing key download is required.

Windows prerequisites

• Windows 10/11 with Docker Desktop configured to use the WSL 2 backend and Linux containers.
• Docker daemon running before installation.
• The Windows setup commands copied from the registered node in Node Management.
• Network access from the Engine container to the configured PostgreSQL upstream and Agata Proxima HTTPS enrollment/heartbeat endpoints.

The Engine is distributed as a Linux container. On Windows, Docker Desktop runs that container through its Linux/WSL 2 backend; this is the supported Windows installation path. The PowerShell installer is a Windows host installer, not an MSI and not a native Windows service binary.

Run the Windows installer

Open PowerShell in the extracted folder. If the machine's execution policy blocks a locally downloaded script, allow it for this PowerShell process only:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install-customer.ps1

The installer performs these checks and actions in order:

1. Generates the node environment file and one-time enrollment-token secret from the copied setup commands.
2. Prompts for the PostgreSQL upstream host and port when it is not already configured.
3. Confirms the Docker CLI and a running Docker daemon.
4. Confirms that Docker is using Linux containers and Docker Compose v2 is available.
5. Validates the customer Compose configuration.
6. Builds and starts the Engine container.
7. Waits up to 120 seconds for the container's Docker health check to report healthy.
8. Prints container status and the local PostgreSQL proxy endpoint.

A successful installation prints Proxima Engine is healthy. Then open Agata Proxima → Nodes/Fleet and confirm the registered node reports healthy after its signed heartbeat arrives. During first enrollment, the Control Plane returns the node heartbeat key and an organization-scoped tenant verification key over HTTPS. The Engine stores both in its protected identity file in a named Docker volume. The Control Plane master signing secret is never sent to customer nodes. After the node is healthy, replace the contents of secrets/node_enrollment_token with enrollment-complete; keep the file in place for subsequent Compose starts.

Verify and operate on Windows

docker compose -f compose.customer.yaml ps
docker compose -f compose.customer.yaml logs --tail 100 engine
$containerId = docker compose -f compose.customer.yaml ps -q engine
docker inspect --format '{{.State.Health.Status}}' $containerId

The final command prints the container health state. To verify SQL connectivity, connect your application or a PostgreSQL client to 127.0.0.1:6432 using the database credentials configured for your upstream PostgreSQL service.

Restart and stop the registered node:

docker compose -f compose.customer.yaml restart engine
docker compose -f compose.customer.yaml down

Start it again without rebuilding:

docker compose -f compose.customer.yaml up -d

Linux installation

Linux customers copy the Linux shell setup commands from Agata Proxima → Nodes and paste them into a shell in the extracted repository folder. The Bash installer creates the environment and enrollment-token secret automatically:

chmod +x ./install-customer.sh
./install-customer.sh

For the Linux deployment-executor service installer and its security requirements, see Customer-managed deployment executor.

Customer-managed deployment executor

The Engine node installer and the deployment executor are separate services:

• Engine node: the PowerShell installer install-customer.ps1 supports Windows hosts using Docker Desktop in Linux-container mode. The Bash installer install-customer.sh supports Linux hosts with Docker Engine and Compose v2. Both install the Engine container and establish signed Fleet heartbeats.
• Deployment executor: this customer-hosted receiver applies approved Engine version changes after Agata sends a signed deployment.created event. It verifies the signature, node identity and version allowlist, performs fixed Compose operations, checks runtime health and reports the observed result to the Control Plane.
• Linux production service: the supplied install-deployment-executor.sh installs the receiver as a protected systemd service. It requires Node.js 22+, Docker Engine/Compose, systemd and a customer-managed HTTPS reverse proxy.
• Windows executor host: the Node.js receiver can run interactively for development or staging. Production requires a customer-managed Windows service wrapper with a protected service account, or a customer-owned orchestrator. The Linux systemd installer is not a Windows service installer.

In Agata Proxima, Deployments → Set up deployment executor creates the dedicated organization API key and signed webhook and returns the one-time deployment-executor.env file. It does not remotely install software or configure DNS. Install the public executor on the customer host first, configure its HTTPS route, then use the dashboard wizard to provision the credentials. Follow the complete customer deployment executor guide for the installation, configuration, security and rollback procedure.

Network and security requirements

• The Engine listens on TCP 6432 and binds to host loopback by default. Keep this binding when the application runs on the same host.
• If the application runs in another container, attach it to the configured Compose network and use the Engine service name and port. For a different host, use a private network/VPN, a deliberate private bind address, and a restrictive firewall rule.
• The configured PostgreSQL upstream address is resolved from inside the Engine container. localhost refers to the container itself, not the Windows host. Use a reachable database hostname or the appropriate Docker Desktop host gateway address.
• Never expose PostgreSQL proxy port 6432, the status interface, or metrics publicly.
• Never commit, email, or paste .env, enrollment tokens, node identity files, operator API keys, or webhook secrets.
• The Control Plane master tenant-signing secret stays in the Control Plane. A customer Engine receives only its own organization's derived verification key during HTTPS enrollment; the Engine stores it in the protected identity file.