Deployment and Infrastructure
Docker: Builder (oven/bun:1.4.0-slim), Python Builder (ubuntu:24.04, Presidio/spaCy 3.7.5+, Python 3.12), Production (ubuntu:24.04, non-root UID 1001, nologin).
Env vars: DATABASE_URL, PORT (8787), MCP_PORT (4000), JWT_SECRET, CHAT_ENCRYPTION_KEY, CREDENTIAL_ENCRYPTION_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, SPACY_MODEL, AGENTWATCH_BACKUP_SECRET, BUN_OPTIONS (set on the Windows NSSM service).
Health: GET /health (30s/10s/60s/3).
Shutdown: SIGINT/SIGTERM -> flush -> 5s wait -> close DB -> force at 15s.
Volumes: /app/logs, /app/data.
Upgrade: Comprehensive SQLite ALTER backfills run at boot; no runtime prisma generate (build-time only).
Deployment modes (three primary)
Section titled “Deployment modes (three primary)”- Cloud-Hosted SaaS — Iterate.ai-hosted multi-tenant instance, fastest time-to-value
- Self-Hosted — Docker on customer infrastructure, data never leaves the corporate network
- Hybrid — control plane in vendor SaaS, data plane in customer VPC (or vice versa)
Deployment tier sizing (T-shirt sizes)
Section titled “Deployment tier sizing (T-shirt sizes)”Three reference configurations cover the majority of customer deployments. All three are pure software — no specialized hardware, no GPU, no SRAM constraints.
| Small (T1) | Medium (T3) | Large (T2) | |
|---|---|---|---|
| Users | up to 300 | 300–500 | 500–1,000+ |
| Footprint | Single Docker container | App container + managed Postgres | App ×2 (HA) + Postgres + Kafka + ClickHouse |
| Database | SQLite + embedded LanceDB | Managed Postgres (RDS / Cloud SQL / Azure DB) | Postgres HA + PgBouncer + read replicas |
| Events | File archiver | File archiver or Kafka | Kafka + Zookeeper |
| Analytics | — | Optional | ClickHouse |
| Vector store | Embedded LanceDB | Embedded LanceDB | Embedded LanceDB |
| Total CPU | 2 vCPU | 6 vCPU | 20 vCPU |
| Total RAM | 2 GB | 8 GB | 32 GB |
| Storage | 20 GB SSD | 120 GB SSD | 540 GB SSD |
| Network | 1 GbE | 1 GbE | 1–10 GbE |
| Approx. cloud cost | ~$40–60/mo | ~$200–300/mo | ~$900–1,300/mo |
Sizing notes: these reference points assume mixed read/write workload. For request-heavy bursty workloads, size on peak requests/sec (see §40). LLM proxy calls are I/O-bound — the bottleneck is upstream provider latency, not AgentWatch CPU. Knowledge Center (full AST + LanceDB + Semgrep + Trivy) is an optional add-on requiring 16 vCPU / 16 GB RAM when enabled.
Minimum software requirements
Section titled “Minimum software requirements”| Component | Minimum |
|---|---|
| Database | PostgreSQL 14+ (managed or self-hosted), or SQLite (embedded — small tier) |
| Event pipeline | Apache Kafka 3.x (optional, file-based fallback included) |
| Analytics | ClickHouse 23+ (optional) |
| Load balancer | HAProxy 2.x, NGINX 1.20+, AWS ALB/NLB, GCP LB, Azure LB |
| Object storage | S3 API-compatible (AWS S3, GCS, Azure Blob, MinIO, Cloudflare R2) |
| Identity provider | Any OIDC-compliant provider (Okta, Microsoft Entra ID, Keycloak, Google Workspace, Auth0, OneLogin) |
| Container runtime | Docker 20.10+, containerd 1.6+, or Kubernetes 1.24+ |
Hardware notes: x86_64 primary, ARM64 (AWS Graviton, Azure Cobalt) supported via multi-arch container images. SSD required for the database tier; NVMe strongly preferred for Postgres + ClickHouse. 1 GbE is sufficient for all tiers — 10 GbE matters only at very high event-streaming volume (> 10K events/sec). No GPU required — LLM inference happens at the upstream provider or on customer-hosted inference clusters (vLLM, TGI, Triton). AgentWatch is the governance and observability layer; CPU/RAM only.
Deployment artifacts (what ships)
Section titled “Deployment artifacts (what ships)”| Artifact | Path | Use |
|---|---|---|
| Docker image | iterateai/agentwatch:<tag> (multi-arch: linux/amd64 + linux/arm64) |
Container deploys; non-root UID 1001 |
| Helm chart | helm/agentwatch/ (Chart.yaml, values.yaml, statefulset/ingress/PVC/service/serviceaccount templates) |
Kubernetes deploys; security context pre-hardened (runAsNonRoot, fsGroup 1000, no privilege escalation, cap_drop ALL + cap_add NET_BIND_SERVICE only) |
| Docker Compose files | docker-compose.yml, docker-compose.efs.yml, docker-compose.event-pipeline.yml |
Quick-start single-host + EFS + Kafka/ClickHouse-enabled variants |
| Single binary | Bun-compiled, minified, no source exposure | Air-gapped + edge installs |
| MCP-server binary | Separate compiled binary (knowledge-extractor) | When the Knowledge Center is deployed standalone |
| Postman test collection | AgentWatch_Test_Collection.postman_collection.json (~1.2 MB, full coverage of proxy / DLP / audit / MCP / SSO / SCIM / webhook flows) + AgentWatch_Test_Environments.postman_environment.json |
Smoke testing, partner-handoff acceptance, CI regression |
| Newman runner | newman-runner.sh |
Automated CI execution of the Postman collection |
| Python bridge | python-bridge/presidio_ner.py + requirements.txt + setup.sh |
Presidio + spaCy NER sidecar (bundled into the Docker image) |
| Enrichment microservice | enrichment-service/ (separate Bun-based Express service, default port 3101) |
Optional companion service for agent enrichment, MCP knowledge sources, and injectKnowledge() workflows |
| Architecture one-pagers | docs/architecture-one-pagers/ (HTML diagrams) |
Sales + partner enablement collateral for each deployment pattern |
| Install / build scripts | start.sh, build.sh, build.ps1, dump_db.sh, import_db.sh |
End-to-end operational tooling |
Reference deployment topologies (six patterns)
Section titled “Reference deployment topologies (six patterns)”| Topology | When to use |
|---|---|
| 1. Direct integration | Apps → AgentWatch → LLM providers over the public internet. Simplest pattern; appropriate for dev, internal tools, and low-compliance use cases. |
| 2. With Zscaler / CASB | All AgentWatch egress traverses the customer’s corporate proxy (Zscaler, Forcepoint, Netskope). Required for regulated enterprises with mandatory CASB controls. Configured via HTTPS_PROXY env vars. |
| 3. Load-balanced HA | AgentWatch deployed as multiple replicas behind HAProxy / ALB / NLB, with Postgres primary + replicas and Kafka cluster. For production at 500+ users with formal SLA requirements. |
| 4. Transparent proxy | Customer DNS resolves OpenAI / Anthropic / Vertex AI hostnames to AgentWatch. No application code change required — drop-in shadow-AI elimination for brownfield environments. |
| 5. Equinix / colo dedicated egress | AgentWatch deployed in customer cloud, egressing via dedicated Equinix interconnect to LLM provider regions for low-latency, predictable-cost routing. |
| 6. Customer-hosted inference | AgentWatch in front of customer-operated inference clusters (vLLM, TGI, Triton, llama.cpp). All traffic stays inside customer boundary — strongest data-residency posture. |
Additional deployment modes layered on top of the six patterns:
| Mode | Notes |
|---|---|
| Developer laptop | Single binary + SQLite + Ollama. Offline-capable. (2 vCPU / 4 GB) |
| SaaS / multi-tenant hosting | Enterprise + Stripe billing + per-org isolation (resellable AI gateway). |
| Hybrid cloud | Control plane on managed cloud, data plane in customer VPC, traffic split by tenant. |
| Air-gapped / Dark Site | Docker + SQLite + Ollama; zero outbound dependency. Container images, model weights, and library mirrors pulled from a local registry (Harbor) once at install time. Local log shipping (Splunk/ELK) over on-prem socket; no cloud-vendor proxy in the loop. Suitable for FCC-regulated, classified, or sovereign-cloud deployments. |
| Multi-region active/active | Stateless app tier + Postgres cross-region read replicas + global DNS load balancer. |
Data residency: each deployment is region-local by design. All audit, usage, and embedding data stays inside the deployment region — only LLM calls leave the region, and only to the providers the customer explicitly authorizes. This applies even in the SaaS topology when configured for tenanted regional deployment.
Local container registry: any OCI-compliant private registry works (Harbor, JFrog Artifactory, AWS ECR, Azure ACR, GCR, Quay). Image-signature enforcement is the registry’s job — AgentWatch images can be Cosign- or Notation-signed and gated by registry policy.
In-region / data sovereignty: when deployed in-region, the control plane, data plane, log aggregation, and model inference can all stay inside the regional boundary. The only outbound dependencies are the LLM providers the customer chooses to enable — and those can be replaced by self-hosted Ollama / vLLM / TGI for full sovereignty.