Production Guide¶
AgentLoop has three production surfaces:
- Python package: install the tracing SDK and CLI into agent services.
- API service: receive traces, enforce API keys, store runs, and serve reports.
- Dashboard: inspect traces, usage, optimization plans, and value reports.
Required configuration¶
Set secrets outside source control and configure the public origins explicitly:
AGENTLOOP_STORE_BACKEND=postgres
AGENTLOOP_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/agentloop
AGENTLOOP_REQUIRE_API_KEY=true
AGENTLOOP_ADMIN_API_KEY=<long random admin secret>
AGENTLOOP_CORS_ORIGINS=https://dashboard.example.com
AGENTLOOP_API_URL=https://api.example.com
AGENTLOOP_DATABASE_URL (or DATABASE_URL) remains the highest-priority Postgres
connection setting. Percent-encode reserved username and password characters when they are
embedded in a URL. Deployments that can provide separate libpq settings may avoid a
secret-bearing URL entirely:
AGENTLOOP_STORE_BACKEND=postgres
PGHOST=db.example.com
PGPORT=5432
PGDATABASE=agentloop
PGUSER=agentloop
PGPASSWORD=<database password>
For file-backed secrets, set AGENTLOOP_POSTGRES_PASSWORD_FILE instead of
PGPASSWORD. The file is read only when no complete database URL is configured.
AGENTLOOP_ADMIN_API_KEY protects hosted API-key creation. When API auth is enabled,
POST /v1/api-keys returns 503 unless the admin secret is configured.
The Python client's credential handling is endpoint-specific. AgentLoopClient.from_env()
may load both credentials, but sends X-AgentLoop-Key only on ordinary project requests
and X-AgentLoop-Admin-Key only on POST /v1/api-keys; the headers are never sent together.
Keep the admin secret in trusted management processes and do not use it for trace uploads,
reports, findings, usage, health checks, or other ordinary API calls.
Before deploying or promoting an environment, run:
After the API is deployed and the database is reachable, run the full gate:
The production check fails unless Postgres, API-key auth, a strong admin key, explicit CORS origins, and an HTTPS API URL are configured.
Docker Compose¶
For a local production-like stack:
Compose passes POSTGRES_PASSWORD to the database, API, and dashboard through a
Docker secret. It is never interpolated into a connection URL, so URI-reserved punctuation
such as /, ?, #, %, @, and : is supported without encoding. Validate
configuration with docker compose config --quiet; avoid printing rendered production
configuration because other environment values may still be sensitive.
Services:
- API:
http://localhost:8000 - Dashboard:
http://localhost:8501 - Postgres: internal
db:5432
Create a project API key:
uv run agentloop remote-create-api-key --project-id acme --name prod \
--api-url http://localhost:8000 \
--admin-api-key "$AGENTLOOP_ADMIN_API_KEY"
Upload a trace:
uv run agentloop upload --path runs/research_agent_baseline.json \
--api-url http://localhost:8000 \
--api-key al_xxx
Run the production smoke check:
AGENTLOOP_API_URL=http://localhost:8000 \
AGENTLOOP_ADMIN_API_KEY="$AGENTLOOP_ADMIN_API_KEY" \
uv run python scripts/smoke_api.py
The official image uses Python 3.15, which is exercised by the package CI matrix and by
the end-to-end container deployment smoke. The repository keeps Python 3.13 in
.python-version for the default contributor and standalone-build environment, while the
package remains tested across Python 3.11, 3.13, 3.14, and 3.15. The lockfile selects
compatible binary wheels for the image. Source builds require Python 3.11 or newer
because the patched Pillow and filelock releases no longer support Python 3.10.
CI installs released interpreters and excludes prerelease fallbacks.
The image runs as the non-root
agentloop user. Application files under /app are read-only to that user; /data is the
intended writable path for SQLite deployments.
Use uv run agentloop production-check --allow-http only for local staging URLs such as
http://localhost:8000; public production traffic should use HTTPS.
Diagnosis reads and writes¶
Application endpoints use /v1. Configure AGENTLOOP_API_URL as the origin or
mount path, without the version suffix; the Python client adds /v1 itself.
Upgrade servers before clients. Unversioned application aliases remain supported
throughout 0.x and can be removed no earlier than 1.0 with release notice.
/health and /readyz remain supported operational aliases. See
API versioning for the full route map and compatibility policy.
| Operation | Behavior |
|---|---|
GET /v1/traces/{run_id}/diagnosis |
Compute the current diagnosis without changing stored findings. |
POST /v1/traces/{run_id}/diagnosis |
Recompute and persist findings, including lifecycle updates. No request body is required. |
GET /traces/{run_id}/diagnose |
Deprecated read-only alias of the GET operation. |
All three operations require the same project API key and return 404 for a
trace outside that project. Repeated GET requests cannot insert, update, or
supersede findings. POST preserves accepted/resolved/dismissed decisions for
unchanged findings and supersedes active findings no longer emitted by diagnosis.
from agentloop import AgentLoopClient
client = AgentLoopClient.from_env()
preview = client.get_diagnosis("run_id") # Compute without persisting.
saved = client.save_diagnosis("run_id") # Explicitly recompute and persist.
agentloop remote-diagnose RUN_ID uses POST and retains its existing persistence
behavior. The local diagnose command and dashboard diagnosis view compute
reports; trace ingestion continues to persist initial findings.
Upgrade the server before upgrading remote clients. Existing callers of GET
/diagnose still receive a diagnosis but must switch to POST if they depended on
its former write side effects. The deprecated alias is available throughout 0.x;
removal will be announced before a 1.0-or-later release.
Health Checks¶
Use these probes in hosting platforms:
/health confirms the API process is up and returns the package version. /readyz
initializes and queries the configured store, so use it for readiness checks.
Database Schema Migrations¶
agentloop/migrations.py holds a small, ordered list of migrations applied by both
SQLiteTraceStore and PostgresTraceStore on every init() call (which every store
method calls before touching data). Applied versions are tracked in a
schema_migrations table. Migrations are idempotent (IF NOT EXISTS / ON CONFLICT
DO NOTHING), so concurrent init() calls from multiple API/dashboard replicas
starting at once are safe without extra locking, and re-running init() never
re-applies or duplicates a migration.
Upgrade. Deploy the new package version and restart the API/dashboard; the next
init() call — which happens automatically on startup and on every request through
the store() dependency — applies any pending migrations before serving traffic. A
database that predates the migration system (no schema_migrations table) is
recognized as already at the pre-#22 baseline schema (migration 0001) because that
migration's CREATE TABLE IF NOT EXISTS statements reproduce the exact schema init()
used to create inline; only the migrations after it run.
Backup. Before upgrading a production database, take a standard backup:
For SQLite, copy the database file while no process holds it open, or use
sqlite3 runs/agentloop.db ".backup agentloop-backup.db".
Rollback. Migrations in this system are forward-only; there is no automated "down"
migration. To roll back, restore the pre-upgrade backup and redeploy the previous
package version. Because each migration is applied inside a single transaction (init()
opens one connection per call and commits only after every pending migration in that
call succeeds), a failed migration leaves the schema at its last successfully applied
version — it never partially applies. The MigrationError raised on failure names the
migration version and reports the underlying database error to guide recovery (e.g.
free disk space, resolve a blocking lock) before retrying.
Compatibility. Migration 0002 (issue #10) de-duplicates any usage_events rows
that predate the per-run uniqueness constraint, keeping the most recent row per
(project_id, run_id), before adding the constraint — so upgrading a store that
already has duplicate usage rows from retried saves is safe and does not fail.
Migration 0003 (issue #19) only adds indexes and has no data impact.
Package Release¶
Tag releases as vX.Y.Z. The release workflow builds the Python package and can
publish to PyPI when the repository has a trusted-publishing PyPI environment
configured.
Deployment Notes¶
- Use Postgres for hosted API/dashboard deployments.
- Keep SQLite for local demos and single-user development only.
- Set
AGENTLOOP_REQUIRE_API_KEY=truefor internet-facing APIs. - Set
AGENTLOOP_CORS_ORIGINSto the exact dashboard origin. - Rotate
AGENTLOOP_ADMIN_API_KEYlike any other production secret. - Rotate the Compose database password in both Postgres and the Docker secret, then recreate
the database, API, and dashboard containers and rerun readiness plus the smoke check.
POSTGRES_PASSWORDinitializes only a new, empty Postgres data volume; changing the.envvalue alone does not update an existing database role. Use an authenticated Postgres password-change procedure before replacing the secret, and keep the old value only until the recreated clients connect successfully. - The Streamlit dashboard does not provide end-user authentication. Treat it as an operator console: keep it on a private network or place it behind an authenticated reverse proxy. Do not expose it directly to the internet.
- Terminate TLS at a trusted proxy or load balancer and forward only the API and authenticated dashboard routes that users need.
- Apply request-body limits, rate limits, timeouts, and access logging at the proxy. Trace payloads can be large and may contain sensitive prompts or tool data.
- Restrict database network access to the API and dashboard workloads, require encrypted database connections in hosted environments, and test backups and restores.
- Retain traces only as long as needed. Establish a deletion and redaction policy before ingesting production or customer data.
The Compose ports bind to 127.0.0.1 by default to keep the local stack off the
LAN. Use an explicit production deployment configuration instead of weakening
those bindings in the checked-in development file.