How Agent Access Manager is deployed

A plain-language tour of the moving parts: what runs where, what each external piece is for, and how a single box grows into a cluster. This is the operator's view; the packaging and scale-out engineering is in delivery and operations.

One image, layered overlays

There is a single application image and a single dashboard. You choose an edition by deciding which optional infrastructure to switch on, layered as compose overlays (or Helm values) on the base stack. Nothing below is a different build, so growing from Core to Pro to Distributed is a configuration change, not a migration or a reinstall. (The edition matrix is on the guide landing.)

Standalone vs distributed

Standalone (single host)Distributed (scale-out)

Everything on one machine: the app, Postgres, and whichever overlays you enable (OpenSearch for Pro, the AI sidecars for Pro AI, bundled Keycloak for SSO). Rate-limit counters live in the JVM and scheduled maintenance just runs. This is the right choice for most on-prem installs.

flowchart TD
    APP["Agent Access Manager (app + dashboard)"]
    PG[("PostgreSQL")]
    OS[("OpenSearch (Pro)")]
    OBJ[("Object store: local dir")]
    SMTP["SMTP server"]
    AISRV["AI servers / vendors"]
    APP --> PG
    APP -.Pro.-> OS
    APP --> OBJ
    APP -.->|email| SMTP
    APP -->|LLM calls| AISRV

The gateway data plane is stateless, so you run N app replicas behind a load balancer. Shared state moves to external stores so every replica agrees. Single-host multi-replica uses deploy/compose/distributed.yml; multi-machine uses the Helm chart.

flowchart TD
    LB["Load balancer"]
    A1["app #1"]
    A2["app #2"]
    A3["app #N"]
    PG[("PostgreSQL")]
    VK[("Valkey")]
    OS[("OpenSearch")]
    OBJ[("Object store: S3-compatible")]
    LB --> A1 & A2 & A3
    A1 & A2 & A3 --> PG
    A1 & A2 & A3 -->|rate-limit counters + config broadcasts| VK
    A1 & A2 & A3 --> OS
    A1 & A2 & A3 --> OBJ

• Valkey holds the hot rate-limit counters (the only store that scales an org-wide counter across instances) and carries config-change broadcasts, so a change on one replica reloads on all.
• ShedLock makes scheduled maintenance (audit-partition upkeep) a cluster singleton, so it runs once cluster-wide.
• OpenSearch native retention/snapshots are scheduler-free, so they need no cross-instance coordination.

The external pieces, and what each is for

AI servers (your vendors and local models)

These are the upstream LLM endpoints Agent Access Manager proxies to: OpenAI, Anthropic, Gemini, Vertex, or anything OpenAI-compatible you self-host (Ollama, vLLM, Groq, LiteLLM). You connect them in Operate ▸ Catalog as providers; their master keys are encrypted at rest and never reach your applications. A self-hosted Ollama or vLLM keeps inference fully on-prem.

PostgreSQL (always)

The system of record for all governance config (orgs, keys, catalog, budgets, guardrails, rules) and, on Core/Base, the audit trail (audit_event, month-partitioned). Tables reference tenants and scopes by value, not by foreign key, so the hot path is decoupled. This is the one component every edition needs.

Valkey (distributed only)

The open-source Redis fork. It backs the rate-limit counters when you run more than one app replica (atomic increments on per-minute buckets) and the config-broadcast pub/sub that keeps caches consistent across replicas. On a single box it is unnecessary: the in-JVM counter is used and broadcasts are a no-op. Selected by aim.ratelimit.backend / aim.cluster.backend.

OpenSearch (Pro)

The Apache-2.0 search engine (not Elasticsearch) that holds the SIEM projection: every governance event, normalised and indexed for fast search and aggregation. Turning it on (aim.siem.enabled) lights up the Investigate group and promotes OpenSearch to the audit system of record, with native ISM retention and optional snapshot archival (hot → archive → delete) to a filesystem or any S3-compatible store. It owns its own data and never reads another module's tables, so it can be scaled or split off independently.

Object storage (reports)

Where generated report artifacts live, kept out of the database. One knob, aim.objectstore.backend:

• fs (Core): a local directory. Fine for a single box.
• s3 (Pro / Distributed): any S3-compatible store (SeaweedFS, MinIO, AWS S3, Cloudflare R2, Wasabi, B2). Required when multiple replicas must all serve a download.

Every object is AES-256-GCM encrypted at rest transparently, so the bucket only ever holds ciphertext and no feature does its own at-rest crypto. The same knob also drives the OpenSearch snapshot repository type. Internals: object store.

SMTP (email)

A mail server you point Agent Access Manager at (in Settings ▸ Mail server) so it can send notification emails and emailed reports. It is per-org and optional: webhooks and in-app notifications need no mail server. There is a send-test to verify it.

SSO: Keycloak or your IdP

Sign-in for the admin plane is SSO-first. Agent Access Manager can bundle Keycloak (behind the same host at /auth) or validate tokens from your existing OIDC provider. People authenticate at the IdP; Agent Access Manager only validates the resulting token (signature, issuer, expiry, audience) and maps roles. The human session and any password/MFA live at the IdP, never in Agent Access Manager. The local Basic admin remains as break-glass. Set with aim.admin.oidc.issuer-uri. Details: authentication.

What each edition turns on (recap)

Piece	Core	Pro	Pro AI	Distributed
App + PostgreSQL	✅	✅	✅	✅
Object store	local dir	local dir	local dir	S3-compatible
OpenSearch (SIEM + audit SoR)	-	✅	✅	✅
AI guardrail sidecars (Presidio / Llama Guard)	-	-	✅	optional
Valkey (cross-instance counters + broadcasts)	-	-	-	✅
SMTP, SSO	optional	optional	optional	optional

Start small, grow in place

Begin on Core (app + Postgres). Add OpenSearch when you want security operations and longer audit retention (Pro). Add the AI sidecars when regex guardrails are not enough (Pro AI). Move counters to Valkey and the object store to S3 when you scale past one replica (Distributed). The dashboard and the data you have collected carry across unchanged.

---

Back to the guide landing, or dig into the engineering in delivery and operations.