Configuration

The engine reads all configuration from CLI flags and environment variables - nothing you edit by hand (the config.json under AGENTX_HOME is engine-owned state, not a config file). Everything has a working default: a bare agentx-server boots SQLite on port 4700 with no keys and no auth.

Core

Variable / flag	Default	Description
`--dev`	off	Opens the dashboard in your browser on startup. The API behaves identically without it.
`--upgrade`	off	Re-downloads the latest dashboard bundle before serving, even when one already exists. See Upgrading.
`--port` / `PORT`	`4700`	Port for the engine’s HTTP API (the dashboard is served on the same port).
`--db-url` / `AGENTX_DB_URL`	local SQLite	Postgres connection string, e.g. `postgres://user:pass@host:5432/db`.
`--engine-bin`	auto-detected	Overrides which engine executable `agentx-server` launches.
`AGENTX_HOME`	`~/.agentx`	Where the SQLite file (`agentx.db`) and `config.json` live.
`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY`	unset	Unlock the LLM-judge features (evaluation scoring, LLM judge scorers, semantic patterns, suggestion drafting, Playground). Also settable live from Platform Settings. Trace ingest and phrase/regex patterns need none.
`AGENTX_LOG_LEVEL`	`info`	Log level for the engine’s structured JSON log lines on stdout. Pipe through `pino-pretty` for colors in dev.
`AGENTX_WEB_FORCE`	unset	`1` lets `--upgrade` replace a locally-built dashboard bundle that is newer than the latest release (a deliberate roll-back). Without it, `--upgrade` keeps the newer local build and logs a warning. See Upgrading.

--port and --db-url are flags of the agentx-server launcher, which translates them into the PORT / AGENTX_DB_URL environment variables before handing off to the engine; --engine-bin only tells the launcher which engine executable to start. The Docker image runs the engine binary directly - no launcher in between - so set the environment variables there.

Deployment tiers

One engine binary, one wire API - the tier is a deployment choice, never a fork:

Tier	Control plane	Telemetry (spans)	Configure with
Self-host	SQLite	SQLite, same file	nothing - the default
Team	Postgres	Postgres	`AGENTX_DB_URL=postgres://...`
Enterprise	Postgres	ClickHouse	`AGENTX_DB_URL=...` + `AGENTX_TELEMETRY_URL=http://user:pass@ch:8123/db`

Variable	Default	Description
`AGENTX_TELEMETRY_URL`	unset	ClickHouse URL for span storage (the enterprise tier). Unset keeps spans in the same SQLite/Postgres database as everything else. The boot log confirms with `Telemetry store: ClickHouse (...)`.
`AGENTX_TELEMETRY_TTL_DAYS`	`90`	ClickHouse span retention, baked into the table’s TTL on first boot. Changing it later needs `ALTER TABLE agentx_spans MODIFY TTL`.
`AGENTX_PG_PARTITION_RETENTION_DAYS`	unset (keep everything)	Partitioned-Postgres tier: whole daily partitions older than this are dropped by the daily maintenance timer. Fresh Postgres installs get a natively partitioned traces table; pre-existing databases keep their non-partitioned table and row-delete retention (detected automatically).

The repo ships an enterprise reference deployment as docker-compose.enterprise.yml (Postgres + ClickHouse + one engine) and a Helm chart at deploy/helm/agentx (build and push the repo Dockerfile first - no public image is published yet; postgres.externalUrl / clickhouse.externalUrl point it at managed databases). See High availability & DR for the topology rules and engine/docs/deployment-tiers.md in the repo for the full walkthrough, including how to verify spans actually land in ClickHouse.

Using Postgres

AGENTX_DB_URL=postgres://user:pass@host:5432/agentx agentx-server --dev

Tables are created and migrated automatically at boot - no separate migration step. SQLite (default) is a real, durable option for a single-machine install; reach for Postgres when you want managed backups, point-in-time recovery, or higher retention.

Ingest and rate limits

Variable	Default	Description
`AGENTX_INGEST_FLUSH_MS`	`10`	Micro-batch window: ingest requests arriving inside it share one INSERT.
`AGENTX_INGEST_FLUSH_SIZE`	`500`	Early-flush batch size.
`AGENTX_INGEST_QUEUE_MAX`	`10000`	Bound on the ingest queue; beyond it ingest sheds load with 429 + `Retry-After` (SDKs back off and redeliver; span ids make retries idempotent).
`AGENTX_INGEST_MAX_FIELD_CHARS`	`100000`	Per-field payload cap (serialized length). Oversized fields are truncated with an explicit marker.
`AGENTX_RATE_LIMIT_CREDENTIAL`	`120`/min	Request ceiling per IP for the credential surface (sign-in, anything that hands out or is guarded by a key).
`AGENTX_RATE_LIMIT_DATA_PLANE`	`6000`/min	Request ceiling per IP for the data plane - far above any real SDK burst; exists only to bound key-guessing loops.
`AGENTX_RATE_LIMIT`	on	`off` disables rate limiting entirely (benchmarks, or when the load balancer rate-limits instead). Counters are per-process and per-IP.

Monitoring behavior

Variable	Default	Description
`AGENTX_MONITOR_CHILD_SPANS`	`false`	Online scoring runs on root spans only (scoring a tool call’s output as if it were the whole interaction is misleading, and it multiplies judge calls per trace). `true` restores per-span scoring.
`AGENTX_OTEL_MONITOR`	`true`	Traces arriving via the OTLP endpoint (`/api/v1/otel/v1/traces`) are monitored by default - pointing an OTel exporter here is itself the opt-in. `false` disables.
`AGENTX_SESSION_SWEEP`	`true`	`false` disables the background sweep that judges idle sessions for session-scoped judge scorers (`POST /api/v1/agent-monitoring/session-sweep/run` still works on demand).
`AGENTX_SESSION_SWEEP_WINDOW_HOURS`	`24`	How far back the session sweep looks for judgeable sessions. Bucketed: up to 24 means 24h, up to 168 means 7d, above that 30d.
`AGENTX_ALERT_SWEEP`	`true`	`false` disables the background evaluator for alert rules (`POST /api/v1/agent-monitoring/alert-rules/sweep/run` still works on demand). Email channels need one of the mailer variables below.
`AGENTX_IMPROVEMENT_SWEEP`	`true`	`false` disables the background sweep that drafts and validates improvement proposals for the Improvement Inbox (`POST /api/v1/evaluate/improve/inbox/sweep/run` still works on demand).

Quotas

Variable	Default	Description
`AGENTX_QUOTA_JUDGE_CALLS_PER_DAY`	unset (unlimited)	Daily cap on judge LLM calls - per organization in multi-tenant mode, per instance otherwise.
`AGENTX_QUOTA_ONLINE_JUDGE_CALLS_PER_DAY`	unset (unlimited)	Daily per-project cap on live judge calls - per-trace and per-session judge scorers plus scorer-group judge members share one budget - on top of the global judge quota.
`AGENTX_QUOTA_TRACES_PER_DAY`	unset (unlimited)	Daily cap on ingested root traces, per project. Child spans of existing traces don’t count.

Today’s usage against all three caps is visible read-only in the dashboard (Platform Settings → Usage & limits) and on the wire (GET /api/v1/agent-monitoring/usage - { day, resetsAt, traces, onlineJudgeCalls, judgeCalls }, each { used, limit } with limit: null meaning unlimited). Counters reset at midnight UTC. The caps themselves are deliberately not editable from the UI - they are cost-control levers, changed where deployments are changed.

Auth and multi-user

The default posture is auth-disabled: a reachable port is a trusted user, and the dashboard connects itself. Everything below only matters once you turn on real accounts - see Authentication for the full model.

Variable	Default	Description
`AGENTX_AUTH`	`disabled`	`enabled` turns on real user accounts for the dashboard - owner setup on first boot, sessions, org-scoped project keys. See Authentication.
`AGENTX_AUTH_SECRET`	auto-generated	Session-signing secret. Unset, one is generated on first enabled boot and persisted in the database, so sessions survive restarts with no setup step. Set it explicitly when several environments must share one secret.
`AGENTX_MULTI_TENANT`	`false`	With auth enabled: every signup gets its own organization + seeded project, per-org LLM keys and pricing catalog, invitations via Settings → Team. The SaaS/multi-tenant posture - see Authentication.
`AGENTX_EGRESS_ALLOW_PRIVATE`	unset	Multi-tenant only. Server-side fetches of caller-supplied URLs (webhooks, external scorers, agent connectors, Playground tools, MCP servers) refuse loopback and private-network targets under `AGENTX_MULTI_TENANT=true`, since those URLs arrive in per-tenant request bodies. `1` opts back in for deployments whose tenants legitimately target internal hosts. Single-tenant installs allow private targets by default (cloud metadata endpoints are always refused).
`AGENTX_PUBLIC_URL`	unset	The externally-reachable base URL: cookie/redirect correctness behind a proxy in enabled mode, the base for password-reset and verification links (REQUIRED on any mail-sending deployment - without it those links derive from the request’s Host header, which a client can forge; the engine warns at boot), and the base for the MCP OAuth callback.
`AGENTX_TRUSTED_ORIGINS`	unset	Comma-separated extra origins allowed to hit the auth routes in enabled mode.
`AGENTX_OPEN_SIGNUP`	unset	Enabled mode only. By default, signing up grants NO organization membership once the org has a member - teammates join by accepting an invitation (Settings → Team), so an exposed port cannot hand your projects to a stranger who self-registers. `true` restores auto-join for closed networks.
`AGENTX_TRUST_PROXY`	unset	Behind a reverse proxy, set to `true` (or a hop count / CIDR, Express `trust proxy` semantics) so rate limits and audit rows see the real client IP instead of the proxy’s. Leave unset on a directly-exposed port - trusting the header there lets clients spoof their IP.
`AGENTX_ADMIN_TOKEN`	unset	Unlocks the operator endpoints (send as `x-admin-token`): `GET /api/v1/admin/overview` (per-org members, projects, 24h judge/trace usage) and `GET /api/v1/admin/audit` (the instance-wide audit trail). Unset = the endpoints don’t exist.

Email

Variable	Default	Description
`AGENTX_RESEND_API_KEY`	unset	Sends auth email (invitations, password reset, verification) through Resend. Configuring any mail transport turns on the dashboard’s “Forgot password?” flow.
`AGENTX_SMTP_URL`	unset	Alternative mail transport: an SMTP connection URL, e.g. `smtp://user:pass@smtp.example.com:587`.
`AGENTX_EMAIL_FROM`	`AgentX <noreply@localhost>`	From address for auth email.
`AGENTX_EMAIL_DEBUG_DIR`	unset	Dev-only mail transport: writes each email as a JSON file into this directory instead of sending it.
`AGENTX_REQUIRE_EMAIL_VERIFICATION`	`false`	With a mail transport configured: new accounts must click a verification link before signing in.

Variable	Default	Description
`AGENTX_GOOGLE_CLIENT_ID` / `AGENTX_GOOGLE_CLIENT_SECRET`	unset	Enables “Continue with Google” on the sign-in screen. OAuth callback: `<AGENTX_PUBLIC_URL>/api/v1/auth/callback/google`.
`AGENTX_GITHUB_CLIENT_ID` / `AGENTX_GITHUB_CLIENT_SECRET`	unset	Enables “Continue with GitHub”. OAuth callback: `<AGENTX_PUBLIC_URL>/api/v1/auth/callback/github`.
`AGENTX_OIDC_ISSUER` / `AGENTX_OIDC_CLIENT_ID` / `AGENTX_OIDC_CLIENT_SECRET`	unset	Generic OIDC SSO: point the trio at any IdP that serves `<issuer>/.well-known/openid-configuration` (Okta, Entra ID, Auth0, Google Workspace, Keycloak, …) and an SSO button appears on the sign-in screen. Callback URL to register with the IdP: `<AGENTX_PUBLIC_URL>/api/v1/auth/callback/oidc` (engines older than better-auth 1.7 used `/api/v1/auth/oauth2/callback/oidc`; update the IdP redirect URI when upgrading). SAML and SCIM are not supported.
`AGENTX_OIDC_NAME`	`SSO`	The SSO button’s label, e.g. `Okta`. Cosmetic only.

Wire casing

The API’s one wire convention is camelCase (sessionId, latencyMs, judgeScorers). The trace-ingest write path historically accepted snake_case keys (session_id, latency_ms, …); those remain accepted as legacy aliases for existing SDKs, and POST /ingest/traces answers with both traceId (canonical) and trace_id (legacy). New endpoints and fields are camelCase only.

The project API key

The startup log’s Default project API key: agtx_local_... is generated once on first run and reused after that (persisted in $AGENTX_HOME/config.json). It’s what SDK/CI/OTel callers send as x-api-key. In the default auth-disabled mode the dashboard fetches it automatically from GET /api/v1/auth/config, so there is nothing to paste. Additional projects (created from the project switcher) each get their own key, visible in that project’s Settings → API key.

Prometheus metrics

GET /metrics serves Prometheus text format on the engine’s one port - open by default (the content is deliberately operational-only: queue counters, RSS, uptime; never span content, keys, or per-project data). Internet-exposed deployments set AGENTX_METRICS_TOKEN and scrape with Authorization: Bearer <token>:

curl -H "Authorization: Bearer $AGENTX_METRICS_TOKEN" http://localhost:4700/metrics

Variable	Default	Description
`AGENTX_METRICS_TOKEN`	unset (`/metrics` open)	When set, `GET /metrics` requires `Authorization: Bearer <token>`; requests without it get a `401`.

Metric	Type	Meaning
`agentx_ingest_queue_depth` / `agentx_ingest_queue_max_depth`	gauge	Spans currently queued for flush, and the high-water mark.
`agentx_ingest_spans_total` / `agentx_ingest_spans_stored_total`	counter	Spans accepted into the queue / durably stored.
`agentx_ingest_spans_deduped_total`	counter	Replays deduped by the idempotency key.
`agentx_ingest_spans_rejected_total`	counter	Spans shed with 429 (queue full).
`agentx_ingest_spans_dropped_total`	counter	Spans lost after a failed batch retry - should be 0; above zero is an incident (see the repo’s `engine/docs/runbook.md`).
`agentx_ingest_batches_total`	counter	Flush batches executed.
`agentx_process_resident_memory_bytes` / `agentx_process_uptime_seconds`	gauge	Process RSS and uptime.

The audit trail

The engine keeps an append-only audit log of control-plane activity: scorer/judge/pattern create-update-delete, settings changes, API key regenerations, project create/delete, bulk export reads, and (in AGENTX_AUTH=enabled mode) sign-in/sign-up/sign-out attempts with the attempted email and status. Data-plane traffic (trace ingest, feedback, outcomes) is deliberately excluded so the trail stays readable, and recorded summaries carry field names only, never values - scripts, keys, and passwords cannot leak into the log.

# Instance-wide, operator token required (AGENTX_ADMIN_TOKEN)
curl -H "x-admin-token: $TOKEN" \
  "http://localhost:4700/api/v1/admin/audit?since=2026-08-01&action=scorer.create&limit=100"

# Org-scoped, session cookie (enabled mode): your own organizations' projects only
curl -b "$SESSION" http://localhost:4700/api/v1/auth-org/audit

Rows are immutable by construction: the engine contains an insert and a read for audit_events and nothing else - no update or delete surface exists.

Verifying end-to-end

The repo ships a smoke test that runs the real Python SDK against a fresh instance - Trace, Evaluate (judge scoring), and Monitor (built-in + custom pattern detection). It needs an OPENAI_API_KEY (for the judge paths) and Python 3:

OPENAI_API_KEY=sk-... ./scripts/smoke-test.sh

# Or against a throwaway Postgres instead of SQLite:
OPENAI_API_KEY=sk-... AGENTX_DB_URL=postgres://postgres:agentx@localhost:55432/agentx \
  ./scripts/smoke-test.sh

OpenRouter

Save an OpenRouter API key (Platform Settings → LLM providers, or OPENROUTER_API_KEY in the environment) and every model field in the product - the platform model picker, judge scorers, the playground - can call the full OpenRouter catalog by its vendor/model ids (anthropic/claude-sonnet-4.5, meta-llama/llama-4-maverick, …). Any model id containing / routes through OpenRouter’s OpenAI-compatible API with that key; the model picker lists the live catalog once the key is configured.

Platform model

The engine runs its own LLM operations - topic mapping, suggestions and answer drafts, dataset coverage analysis, prompt/tool proposals, AI analysis, auto-improve reports - on a single default model (gpt-5.6-luna out of the box). Platform Settings → LLM providers → Platform model changes it instance-wide via a searchable picker: direct OpenAI/Anthropic/Gemini names, custom endpoints from the pricing catalog, and - with an OpenRouter key - the whole OpenRouter catalog. This is deliberately separate from judge scorers, which configure their model per scorer; scorers left without a model keep the built-in judge default.

Get Started

Self-Hosting

Python SDK

Guides

Core

Deployment tiers

Using Postgres

Ingest and rate limits

Monitoring behavior

Quotas

Auth and multi-user

Email

Wire casing

The project API key

Prometheus metrics

The audit trail

Verifying end-to-end

OpenRouter

Platform model

​Core

​Deployment tiers

​Using Postgres

​Ingest and rate limits

​Monitoring behavior

​Quotas

​Auth and multi-user

​Email

​Social sign-in and SSO

​Wire casing

​The project API key

​Prometheus metrics

​The audit trail

​Verifying end-to-end

​OpenRouter

​Platform model

Core

Deployment tiers

Using Postgres

Ingest and rate limits

Monitoring behavior

Quotas

Auth and multi-user

Email

Social sign-in and SSO

Wire casing

The project API key

Prometheus metrics

The audit trail

Verifying end-to-end

OpenRouter

Platform model