Deployment

​

Architecture Overview

  [ AI agent machines ]                  [ Your infrastructure ]

    Python SDK
       |  writes JSONL                       +----------------------+
       v                                +--->| PostgreSQL 15+       |
 agenteye-collector --HTTP--+           |    | (relational store)   |
                            |           |    +----------------------+
                            v           |
                       +--------+       |    +----------------------+
                       | Server |<------+--->| ClickHouse 24+       |
                       +--------+       |    | (events / analytics) |
                            ^           |    +----------------------+
                        API |           |
                            |           |    +----------------------+
                      +-----------+     +- - >| Redis 7+ (optional) |
                      | Dashboard |           +----------------------+
                      +-----------+

• Server: Rust HTTP service; receives event batches, writes them to ClickHouse, and maintains relational state in PostgreSQL.
• Dashboard: Next.js web app; reads and writes exclusively through the server API.
• agenteye-collector: deployed on agent machines, not the server host.
• Postgres 15+: REQUIRED. (Raised from 14 in the multi-tenant release; the org-membership schema uses a column-list ON DELETE SET NULL foreign key, which is Postgres 15+. Upgrade Postgres before deploying this version.) Stores OLTP state: api_keys, users, sessions, evaluation_jobs (queue), dashboards, saved_queries, otp_codes, plus the multi-tenant tables orgs, org_memberships, org_settings.
• ClickHouse 24+: REQUIRED. The analytics store for every ingested event. Engine: ReplacingMergeTree, partitioned by month, ordered by (session_id, ts, dedup_key). The server connects via CLICKHOUSE_URL; the bundled deploy/base/clickhouse/ ships a perf-tuned single-node configuration. Multi-tenant requirement: the bundled config enables SQL access management + users_without_row_policies_can_read_rows=false so the server can create one read-only ClickHouse user + row policy per organization (the engine-enforced isolation boundary for the SQL editor and AI agent). If you supply your own ClickHouse config, carry these settings over (see deploy/base/clickhouse/configmap.yaml).
• Redis 7+: optional shared cache + rate-limit backend. Server and dashboard both connect via REDIS_URL. If absent, both degrade gracefully to Postgres-only paths. See Redis (optional cache) below.

​

Server

​

Pull the image

echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
docker pull ghcr.io/agenteye-enterprise/server:beta-latest

Current builds publish under beta-latest; latest is assigned only to stable releases. For production, pin a specific :v<version> tag; see Available Image Tags.

​

Environment variables

​

Run

docker run -d --restart unless-stopped \
  --name agenteye-server \
  -e DATABASE_URL="$DATABASE_URL" \
  -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \
  -e ADMIN_KEY="$ADMIN_KEY" \
  -p 8080:8080 \
  ghcr.io/agenteye-enterprise/server:beta-latest

​

Health check

GET /health    # liveness  - always {"status":"ok"} once the process is up
GET /ready     # readiness - 200 when Postgres + ClickHouse are reachable, else 503

​

Email magic-link URL

1. X-AgentEye-Dashboard-Url header: set automatically by the dashboard’s /api/auth/otp/request proxy from its own public origin. In a same-origin deployment (server and dashboard share a host behind one ingress that forwards proxy headers), no configuration is required.
2. DASHBOARD_URL env var: set this if your dashboard is reachable on a different origin than the one the server’s OTP request endpoint sees (split api.example.com / app.example.com), or if your ingress doesn’t propagate the public host into the dashboard pod (so request.nextUrl.origin would otherwise resolve to a wildcard bind like 0.0.0.0:3000). Example: DASHBOARD_URL=https://app.example.com.
3. Default: https://app.befailproof.ai, used only if neither of the above is present.

kubectl set env deployment/server -n agenteye \
  DASHBOARD_URL=https://app.example.com

​

Dashboard

​

Pull the image

docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest

​

Environment variables

​

Run

docker run -d --restart unless-stopped \
  --name agenteye-dashboard \
  -e AGENTEYE_SERVER_URL="http://your-server-host:8080" \
  -e AGENTEYE_API_KEY="$ADMIN_KEY" \
  -p 3000:3000 \
  ghcr.io/agenteye-enterprise/dashboard:beta-latest

​

Telemetry & privacy

• No agent, session, or event data ever leaves your infrastructure. Only dashboard UI usage is reported. Page URLs are stripped of identifiers before sending, and operators are identified only by an opaque internal id, never by email.
• Telemetry is enabled by default. To turn it off completely, set AE_ANALYTICS_DISABLED=1 on the dashboard container and restart.
• Analytics are sent to the dashboard’s own /ingest path, which the dashboard reverse-proxies to PostHog (https://us.i.posthog.com). Keeping requests first-party means browser ad-blockers don’t drop them. The dashboard container needs outbound access to PostHog; if it’s blocked, telemetry silently does nothing and the dashboard is unaffected.

​

AI Assistant (optional)

​

ClickHouse (required analytics store)

​

Schema

• agenteye.events: ReplacingMergeTree(ingested_at), partitioned by toYYYYMM(ts), ordered by (session_id, ts, dedup_key). Duplicate inserts (collector retries) collapse to a single row at merge time; the server computes a deterministic SHA-256 dedup_key for every event so retries are safe.
• agenteye.evaluations: ReplacingMergeTree(ingested_at), partitioned by toYYYYMM(finished_at), ordered by (session_id, finished_at, dedup_key). Written once per terminal evaluation outcome by the evaluator pipeline. Same dedup-key model as events.
• agenteye.agent_sessions: a VIEW over agenteye.events, not a physical table. Every column is derived (started_at = min(ts), last_event_at = max(ts), ended_at = max(if event_type='agent_end', ts, NULL), event_count = count(), etc.). No per-event upsert and no separate backfill; the view auto-reflects whatever is in events.

​

Configuration

• 2 GiB requested / 4 GiB limit memory in the shipped base overlay (sized to fit small POC/staging nodes); production customers should overlay up — the recommended floor is 2c / 4Gi request, 6c / 8Gi limit. max_server_memory_usage_to_ram_ratio=0.9
• 5 GiB mark cache + 8 GiB uncompressed cache
• background_pool_size=16, background_merges_mutations_concurrency_ratio=2
• MergeTree: parts_to_throw_insert=3000, parts_to_delay_insert=1500, non_replicated_deduplication_window=1000
• local_io_method=auto (io_uring on supported kernels)
• fsync_metadata=0: acceptable because of at-least-once ingest + ReplacingMergeTree dedup
• query_log enabled with 30-day TTL; query_thread_log removed (expensive at high QPS)
• max_execution_time=30 for user-side queries
• 100 GiB PVC at the StatefulSet template (customer overlays SHOULD override to a fast SSD storage class for production)

​

Backups

​

Redis (optional cache)

• Server caches authenticated API-key lookups, the /events/environments + /evaluations/environments lists, the /events/latency_aggregate rollup (the heaviest query the dashboard polls), the /sessions list, and switches OTP-request rate limiting from a Postgres COUNT(*) to a Redis INCR + EXPIRE.
• Dashboard caches validateSession() results so the 10-20 authed API calls a typical page load issues all share one upstream session check. It also rate-limits OTP-request and OTP-verify at the dashboard edge.

​

Configuration

​

Memory + persistence

​

When NOT to deploy Redis

• Single-instance dev/QA. The in-process caches on the server alone deliver most of the per-replica benefit; Redis adds the cross-replica sharing that single-instance setups don’t need.
• Air-gapped installs where the operational cost of running one more service outweighs the latency win.

​

Docker Compose (recommended)

GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \
  --repo agenteye-enterprise/releases \
  --pattern 'docker-compose.yml' \
  --dir ./agenteye
cd agenteye

# Use URL-safe passwords (no /, +, or = characters).
# Generate with: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# Dashboard authentication
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# SMTP for OTP emails (omit to log OTP codes to stdout)
# SMTP_HOST=smtp.yourprovider.com
# SMTP_PORT=587
# SMTP_USERNAME=your-smtp-user
# SMTP_PASSWORD=your-smtp-password
# SMTP_FROM=noreply@yourcompany.com

RUST_LOG=info

docker compose up -d

docker compose down

docker compose down -v

​

Operational settings

​

How the bootstrap works

• For a fresh deploy, set the env vars as shown above and the default org reads them on first boot.
• To change a value later, log into the dashboard and edit it under /<org>/settings. The change applies within seconds across all server replicas; no restart needed.
• A startup log line records what got seeded vs. what was already present, so you can confirm the bootstrap took effect:
  INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true
  

​

Sign-in semantics across organizations

• Session / OTP lifetime: the strictest (shortest) lifetime among the orgs the user belongs to wins.
• Allowed sign-ins: the gate ORs every org’s allowlist together with org membership: a user may request an OTP if any org’s allowlist admits their email or they are already a member of any org.

​

Permissions

• settings:read: see the page and current values.
• settings:write: save changes.

​

Organizations (multi-tenancy)

# Docker Compose - exec into the running server service:
docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp"
docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin

# Kubernetes - exec into the running server Deployment:
kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list

​

Context-window fill

# preview (prints the per-org mutation, changes nothing):
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run
# apply:
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window
# docker compose:
docker compose exec server agenteye-backfill-context-window

​

Production Considerations

• Postgres: Use a managed Postgres service or a dedicated instance with regular backups. The DATABASE_URL supports all standard libpq parameters, including sslmode=require for encrypted connections.
• TLS: Put the server and dashboard behind a reverse proxy (nginx, Caddy, Traefik) that terminates TLS.
• Firewall: The server port (default 8080) should only be reachable from collector machines and the dashboard host, not the public internet.
• Admin key: Set ADMIN_KEY to a strong random secret. After bootstrapping, create dedicated scoped keys for collectors and the dashboard rather than using the admin key everywhere.
• Image tags: Pin to the version in your release manifests (for example, server:v0.0.1-beta.48) in production rather than a floating tag to avoid unintended upgrades. Current beta builds publish under beta-latest; latest is assigned only to stable releases.
• Health monitoring: On Kubernetes the readiness probe uses /ready (Postgres + ClickHouse reachability) while liveness stays on /health. For fleet-wide “is AgentEye itself up?” alerting to Slack, enable the opt-in Robusta add-on; see enterprise-docs/health-monitoring.md.

​

Available Image Tags