From 7ff816a43f3ae114be60dfab9fab46ef57b837ef Mon Sep 17 00:00:00 2001
From: Dipesh Babu
Date: Thu, 19 Nov 2026 19:54:26 -0500
Subject: [PATCH] Add cloud deployment: published image, HTTPS stack and guide
Releases now push the validated image to ghcr.io//agentloop with
version and latest tags after checking it reports the release version
as a non-root user. deploy/ provides a production Compose stack for one
Linux server: Postgres, the API, the dashboard behind a Caddy login and
automatic HTTPS, publishing only ports 80 and 443. A new CI job runs that
stack over HTTPS and checks API key use, the HTTP redirect, the upload
limit, the dashboard login and that internal ports stay unpublished.
docs/CLOUD_DEPLOY.md covers single-server and managed platforms.
Co-Authored-By: Claude Opus 5.5
---
.github/workflows/ci.yml | 117 +++++++++++++++++++
.github/workflows/release.yml | 46 ++++++++
CHANGELOG.md | 9 ++
Dockerfile | 5 +
README.md | 19 ++++
deploy/.env.example | 26 +++++
deploy/Caddyfile | 31 +++++
deploy/docker-compose.yml | 119 ++++++++++++++++++++
docs/CLOUD_DEPLOY.md | 205 ++++++++++++++++++++++++++++++++++
docs/PRODUCTION.md | 7 +-
docs/RELEASING.md | 15 +++
mkdocs.yml | 1 +
12 files changed, 599 insertions(+), 1 deletion(-)
create mode 100644 deploy/.env.example
create mode 100644 deploy/Caddyfile
create mode 100644 deploy/docker-compose.yml
create mode 100644 docs/CLOUD_DEPLOY.md
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e891470..32c000e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -592,3 +592,120 @@ jobs:
- name: Stop deployment stack
if: always()
run: docker compose down --volumes --remove-orphans
+
+ deploy-stack:
+ name: Production deploy stack with HTTPS
+ runs-on: ubuntu-latest
+ env:
+ COMPOSE_FILE: deploy/docker-compose.yml
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+ - name: Build the image the stack deploys
+ shell: bash
+ run: |
+ test "$(grep -c '^FROM python:' Dockerfile)" -eq 1
+ tag="$(sed -n 's|^FROM python:\([^ ]*\).*|\1|p' Dockerfile)"
+ base="$(.github/scripts/pull-official-image.sh "python:$tag")"
+ mirror_file="$RUNNER_TEMP/Dockerfile.deploy"
+ sed "s|^FROM python:$tag|FROM $base|" Dockerfile > "$mirror_file"
+ docker build --pull=false --file "$mirror_file" --tag agentloop:local .
+
+ - name: Pull Postgres and Caddy through the mirror fallback
+ shell: bash
+ run: |
+ echo "POSTGRES_IMAGE=$(.github/scripts/pull-official-image.sh postgres:16-alpine)" >> "$GITHUB_ENV"
+ echo "CADDY_IMAGE=$(.github/scripts/pull-official-image.sh caddy:2)" >> "$GITHUB_ENV"
+
+ - name: Configure synthetic production settings
+ shell: bash
+ run: |
+ dashboard_password="dash-$(openssl rand -hex 16)"
+ admin_key="ci-admin-$(openssl rand -hex 24)"
+ db_password="db-$(openssl rand -hex 16)"
+ echo "::add-mask::$dashboard_password"
+ echo "::add-mask::$admin_key"
+ echo "::add-mask::$db_password"
+ hash="$(docker run --rm "$CADDY_IMAGE" caddy hash-password --plaintext "$dashboard_password")"
+ {
+ echo "AGENTLOOP_IMAGE=agentloop:local"
+ echo "AGENTLOOP_API_DOMAIN=api.localhost"
+ echo "AGENTLOOP_DASHBOARD_DOMAIN=dashboard.localhost"
+ echo "AGENTLOOP_ADMIN_API_KEY=$admin_key"
+ echo "AGENTLOOP_DASHBOARD_USER=operator"
+ echo "AGENTLOOP_DASHBOARD_PASSWORD_HASH='$hash'"
+ echo "POSTGRES_PASSWORD=$db_password"
+ echo "POSTGRES_IMAGE=$POSTGRES_IMAGE"
+ echo "CADDY_IMAGE=$CADDY_IMAGE"
+ } > deploy/.env
+ echo "DASHBOARD_PASSWORD=$dashboard_password" >> "$GITHUB_ENV"
+ echo "AGENTLOOP_ADMIN_API_KEY=$admin_key" >> "$GITHUB_ENV"
+ echo "127.0.0.1 api.localhost dashboard.localhost" | sudo tee -a /etc/hosts
+
+ - name: Validate production Compose configuration without rendering secrets
+ run: docker compose config --quiet
+
+ - name: Start production stack
+ run: docker compose up --detach
+
+ - name: Wait for HTTPS through Caddy
+ shell: bash
+ run: |
+ for attempt in $(seq 1 60); do
+ if docker compose exec -T caddy cat /data/caddy/pki/authorities/local/root.crt > caddy-root.crt 2>/dev/null \
+ && curl --fail --silent --show-error --cacert caddy-root.crt https://api.localhost/readyz > /dev/null; then
+ exit 0
+ fi
+ sleep 3
+ done
+ echo "The API did not become ready over HTTPS" >&2
+ exit 1
+
+ - name: Verify the API over HTTPS
+ shell: bash
+ run: |
+ SSL_CERT_FILE="$PWD/caddy-root.crt" AGENTLOOP_API_URL=https://api.localhost python3 scripts/smoke_api.py
+ status="$(curl --silent --output /dev/null --write-out '%{http_code}' http://api.localhost/v1/health)"
+ test "$status" = 308
+ head -c 17000000 /dev/zero | tr '\0' 'a' > oversized.json
+ status="$(curl --silent --output /dev/null --write-out '%{http_code}' --cacert caddy-root.crt \
+ --header 'Content-Type: application/json' --data-binary @oversized.json https://api.localhost/v1/traces)"
+ test "$status" = 413
+
+ - name: Verify the dashboard requires a login
+ shell: bash
+ run: |
+ status="$(curl --silent --output /dev/null --write-out '%{http_code}' --cacert caddy-root.crt https://dashboard.localhost/)"
+ test "$status" = 401
+ status="$(curl --silent --output /dev/null --write-out '%{http_code}' --cacert caddy-root.crt \
+ --user "operator:wrong-password" https://dashboard.localhost/)"
+ test "$status" = 401
+ for attempt in $(seq 1 40); do
+ if curl --fail --silent --output /dev/null --cacert caddy-root.crt \
+ --user "operator:$DASHBOARD_PASSWORD" https://dashboard.localhost/_stcore/health; then
+ break
+ fi
+ sleep 3
+ done
+ curl --fail --silent --output /dev/null --cacert caddy-root.crt \
+ --user "operator:$DASHBOARD_PASSWORD" https://dashboard.localhost/
+
+ - name: Verify only the proxy is published
+ shell: bash
+ run: |
+ for port in 8000 8501 5432; do
+ if curl --silent --max-time 3 "http://127.0.0.1:$port/" > /dev/null; then
+ echo "Port $port must not be published on the host" >&2
+ exit 1
+ fi
+ done
+
+ - name: Show container logs on failure
+ if: failure()
+ run: docker compose logs --no-color --tail=200
+
+ - name: Stop production stack
+ if: always()
+ run: docker compose down --volumes --remove-orphans
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 93af6ad..792b42b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -78,6 +78,52 @@ jobs:
- name: Publish distribution
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+ publish-image:
+ name: Publish container image
+ needs: [guard, validate]
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ packages: write
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+ - name: Build image from the validated tag
+ shell: bash
+ run: |
+ version="${GITHUB_REF_NAME#v}"
+ image="ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/agentloop"
+ test "$(grep -c '^FROM python:' Dockerfile)" -eq 1
+ tag="$(sed -n 's|^FROM python:\([^ ]*\).*|\1|p' Dockerfile)"
+ base="$(.github/scripts/pull-official-image.sh "python:$tag")"
+ mirror_file="$RUNNER_TEMP/Dockerfile.release"
+ sed "s|^FROM python:$tag|FROM $base|" Dockerfile > "$mirror_file"
+ docker build --pull=false --file "$mirror_file" \
+ --label "org.opencontainers.image.version=$version" \
+ --label "org.opencontainers.image.revision=$GITHUB_SHA" \
+ --tag "$image:$version" --tag "$image:latest" .
+ echo "IMAGE=$image" >> "$GITHUB_ENV"
+ echo "VERSION=$version" >> "$GITHUB_ENV"
+
+ - name: Check the image runs the released version
+ shell: bash
+ run: |
+ actual="$(docker run --rm "$IMAGE:$VERSION" python -c 'import agentloop; print(agentloop.__version__)')"
+ test "$actual" = "$VERSION"
+ docker run --rm "$IMAGE:$VERSION" sh -c 'test "$(id -u)" -ne 0'
+
+ - name: Push to GitHub Container Registry
+ env:
+ GH_TOKEN: ${{ github.token }}
+ shell: bash
+ run: |
+ printf '%s' "$GH_TOKEN" | docker login ghcr.io --username "$GITHUB_ACTOR" --password-stdin
+ docker push "$IMAGE:$VERSION"
+ docker push "$IMAGE:latest"
+ docker logout ghcr.io
+
publish-github:
name: Publish GitHub release
needs: [guard, validate]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8fdfe9f..ce79968 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,15 @@ trace, study, receipt, API and database schema versions.
### Added
+- Cloud deployment. Releases publish a container image to
+ `ghcr.io/dipeshbabu/agentloop` (version and `latest` tags), built from the
+ validated tag and checked to report the release version as a non-root user.
+ `deploy/` adds a production Compose stack for one Linux server: Postgres, the
+ API, the dashboard behind a login, and Caddy with automatic HTTPS, publishing
+ only ports 80 and 443. CI runs the stack over HTTPS and checks API key use,
+ HTTPS redirects, the upload limit, the dashboard login and unpublished
+ internal ports. `docs/CLOUD_DEPLOY.md` covers single-server and managed
+ platform deployments.
- `agentloop improve init --language node` generates a Node.js adapter
(`agentloop_runner.mjs`) for the guided workflow. It imports an agent from a
relative `.mjs`, `.js` or `.cjs` module, calls it as `answer(input, trace)`
diff --git a/Dockerfile b/Dockerfile
index 8599c6b..737c954 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,5 +1,10 @@
FROM python:3.15-slim
+LABEL org.opencontainers.image.title="AgentLoop" \
+ org.opencontainers.image.description="AgentLoop API and dashboard for agent traces and reports" \
+ org.opencontainers.image.source="https://github.com/dipeshbabu/agentloop" \
+ org.opencontainers.image.licenses="Apache-2.0"
+
COPY --from=ghcr.io/astral-sh/uv:0.13.7 /uv /uvx /bin/
ENV PYTHONDONTWRITEBYTECODE=1 \
diff --git a/README.md b/README.md
index 2db2d8d..7d45a33 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@
Trace your code ·
Compare runs ·
Integrations ·
+ Deploy ·
Guide
@@ -409,6 +410,24 @@ code changes.
+## Deploy to the cloud
+
+Run a shared AgentLoop server for your team on any cloud. From 0.2.7 each release
+publishes a container image, `ghcr.io/dipeshbabu/agentloop`, and `deploy/`
+contains a production stack for one Linux server: Postgres, the API, the
+dashboard behind a login, and Caddy for automatic HTTPS. Only ports 80 and 443
+are exposed.
+
+```bash
+cp deploy/.env.example deploy/.env # set the image, domains and secrets
+docker compose -f deploy/docker-compose.yml up --detach
+```
+
+CI runs this exact stack over HTTPS on every change. The
+[cloud deployment guide](https://dipeshbabu.github.io/agentloop/CLOUD_DEPLOY/)
+covers server setup, API keys, upgrades, backups, and managed platforms such as
+Cloud Run, App Runner, ECS and Azure Container Apps.
+
## Dashboard and persistence
From a [source checkout](#source-checkout), load the synthetic example and start
diff --git a/deploy/.env.example b/deploy/.env.example
new file mode 100644
index 0000000..8ddac02
--- /dev/null
+++ b/deploy/.env.example
@@ -0,0 +1,26 @@
+# Copy to deploy/.env and replace every placeholder before starting the stack.
+# Keep deploy/.env out of version control; it holds production secrets.
+
+# Container image. Pin an exact release instead of "latest".
+AGENTLOOP_IMAGE=ghcr.io/dipeshbabu/agentloop:0.2.7
+
+# Public hostnames. Point both DNS records (A/AAAA) at this host first.
+AGENTLOOP_API_DOMAIN=agentloop-api.example.com
+AGENTLOOP_DASHBOARD_DOMAIN=agentloop.example.com
+
+# Admin secret for creating project API keys. Generate with: openssl rand -hex 32
+AGENTLOOP_ADMIN_API_KEY=replace-with-a-long-random-admin-secret
+
+# Dashboard login. Create the bcrypt hash with:
+# docker run --rm caddy:2 caddy hash-password --plaintext 'your-password'
+# Keep the single quotes so Compose does not expand the $ characters in the hash.
+AGENTLOOP_DASHBOARD_USER=admin
+AGENTLOOP_DASHBOARD_PASSWORD_HASH='replace-with-a-bcrypt-hash'
+
+# Database. Mounted as a Compose secret; never embedded in a URL.
+POSTGRES_DB=agentloop
+POSTGRES_USER=agentloop
+POSTGRES_PASSWORD=replace-with-a-long-random-db-password
+
+# Largest trace upload the proxy accepts.
+AGENTLOOP_MAX_UPLOAD=16MB
diff --git a/deploy/Caddyfile b/deploy/Caddyfile
new file mode 100644
index 0000000..012fa75
--- /dev/null
+++ b/deploy/Caddyfile
@@ -0,0 +1,31 @@
+# HTTPS reverse proxy for the AgentLoop production stack.
+# Caddy obtains and renews certificates for both domains automatically once
+# their DNS records point at this host and ports 80 and 443 are reachable.
+
+{$AGENTLOOP_API_DOMAIN} {
+ encode zstd gzip
+ request_body {
+ max_size {$AGENTLOOP_MAX_UPLOAD}
+ }
+ header {
+ Strict-Transport-Security "max-age=31536000"
+ X-Content-Type-Options "nosniff"
+ -Server
+ }
+ reverse_proxy api:8000
+}
+
+# The dashboard has no login of its own, so Caddy requires one.
+{$AGENTLOOP_DASHBOARD_DOMAIN} {
+ encode zstd gzip
+ basic_auth {
+ {$AGENTLOOP_DASHBOARD_USER} {$AGENTLOOP_DASHBOARD_PASSWORD_HASH}
+ }
+ header {
+ Strict-Transport-Security "max-age=31536000"
+ X-Content-Type-Options "nosniff"
+ X-Frame-Options "DENY"
+ -Server
+ }
+ reverse_proxy dashboard:8501
+}
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
new file mode 100644
index 0000000..da1156f
--- /dev/null
+++ b/deploy/docker-compose.yml
@@ -0,0 +1,119 @@
+# Production AgentLoop stack for one Linux host on any cloud.
+#
+# Caddy terminates HTTPS with automatically issued certificates, serves the API
+# on AGENTLOOP_API_DOMAIN and the dashboard behind a login on
+# AGENTLOOP_DASHBOARD_DOMAIN. Only ports 80 and 443 are published; the API,
+# dashboard and Postgres stay on the private Compose network.
+#
+# cp deploy/.env.example deploy/.env # then replace every placeholder
+# docker compose -f deploy/docker-compose.yml up --detach
+#
+# See docs/CLOUD_DEPLOY.md.
+name: agentloop
+
+services:
+ db:
+ image: ${POSTGRES_IMAGE:-postgres:16-alpine}
+ restart: unless-stopped
+ environment:
+ POSTGRES_DB: ${POSTGRES_DB:-agentloop}
+ POSTGRES_USER: ${POSTGRES_USER:-agentloop}
+ POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-agentloop} -d ${POSTGRES_DB:-agentloop}"]
+ interval: 5s
+ timeout: 5s
+ retries: 20
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+ secrets:
+ - postgres_password
+
+ api:
+ image: ${AGENTLOOP_IMAGE:?Set AGENTLOOP_IMAGE in deploy/.env, for example ghcr.io/dipeshbabu/agentloop:0.2.7}
+ restart: unless-stopped
+ environment:
+ AGENTLOOP_STORE_BACKEND: postgres
+ PGHOST: db
+ PGPORT: "5432"
+ PGDATABASE: ${POSTGRES_DB:-agentloop}
+ PGUSER: ${POSTGRES_USER:-agentloop}
+ AGENTLOOP_POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
+ AGENTLOOP_REQUIRE_API_KEY: "true"
+ AGENTLOOP_ADMIN_API_KEY: ${AGENTLOOP_ADMIN_API_KEY:?Set AGENTLOOP_ADMIN_API_KEY in deploy/.env}
+ AGENTLOOP_CORS_ORIGINS: https://${AGENTLOOP_DASHBOARD_DOMAIN:?Set AGENTLOOP_DASHBOARD_DOMAIN in deploy/.env}
+ depends_on:
+ db:
+ condition: service_healthy
+ secrets:
+ - postgres_password
+ healthcheck:
+ test:
+ [
+ "CMD",
+ "python",
+ "-c",
+ "import json, urllib.request; assert json.load(urllib.request.urlopen('http://127.0.0.1:8000/readyz'))['status'] == 'ready'",
+ ]
+ interval: 10s
+ timeout: 5s
+ retries: 12
+
+ dashboard:
+ image: ${AGENTLOOP_IMAGE}
+ restart: unless-stopped
+ command:
+ [
+ "streamlit",
+ "run",
+ "dashboard/app.py",
+ "--server.address=0.0.0.0",
+ "--server.port=8501",
+ "--server.headless=true",
+ "--browser.gatherUsageStats=false",
+ ]
+ environment:
+ AGENTLOOP_STORE_BACKEND: postgres
+ PGHOST: db
+ PGPORT: "5432"
+ PGDATABASE: ${POSTGRES_DB:-agentloop}
+ PGUSER: ${POSTGRES_USER:-agentloop}
+ AGENTLOOP_POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
+ AGENTLOOP_API_URL: http://api:8000
+ depends_on:
+ api:
+ condition: service_healthy
+ secrets:
+ - postgres_password
+
+ caddy:
+ image: ${CADDY_IMAGE:-caddy:2}
+ restart: unless-stopped
+ ports:
+ - "80:80"
+ - "443:443"
+ - "443:443/udp"
+ environment:
+ AGENTLOOP_API_DOMAIN: ${AGENTLOOP_API_DOMAIN:?Set AGENTLOOP_API_DOMAIN in deploy/.env}
+ AGENTLOOP_DASHBOARD_DOMAIN: ${AGENTLOOP_DASHBOARD_DOMAIN}
+ AGENTLOOP_DASHBOARD_USER: ${AGENTLOOP_DASHBOARD_USER:?Set AGENTLOOP_DASHBOARD_USER in deploy/.env}
+ AGENTLOOP_DASHBOARD_PASSWORD_HASH: ${AGENTLOOP_DASHBOARD_PASSWORD_HASH:?Set AGENTLOOP_DASHBOARD_PASSWORD_HASH in deploy/.env}
+ AGENTLOOP_MAX_UPLOAD: ${AGENTLOOP_MAX_UPLOAD:-16MB}
+ volumes:
+ - ./Caddyfile:/etc/caddy/Caddyfile:ro
+ - caddy_data:/data
+ - caddy_config:/config
+ depends_on:
+ api:
+ condition: service_healthy
+ dashboard:
+ condition: service_started
+
+volumes:
+ postgres_data:
+ caddy_data:
+ caddy_config:
+
+secrets:
+ postgres_password:
+ environment: POSTGRES_PASSWORD
diff --git a/docs/CLOUD_DEPLOY.md b/docs/CLOUD_DEPLOY.md
new file mode 100644
index 0000000..7ddf3ac
--- /dev/null
+++ b/docs/CLOUD_DEPLOY.md
@@ -0,0 +1,205 @@
+# Deploy to the cloud
+
+A cloud deployment gives a team one shared AgentLoop server. Developers and CI
+upload traces to it with the Python or TypeScript client, and everyone reviews
+the same traces, findings and reports. The CLI, SDKs and guided workflow keep
+running where your agents run; only the shared server moves to the cloud.
+
+The server has three parts, all started from one container image:
+
+| Part | What it does | Port inside the stack |
+| --- | --- | --- |
+| API | Stores traces and serves reports under `/v1`, with project API keys | 8000 |
+| Dashboard | Streamlit console for traces, findings and comparisons | 8501 |
+| Postgres | Shared storage; schema migrations run automatically on startup | 5432 |
+
+## Container image
+
+From AgentLoop 0.2.7, every release publishes an image to GitHub Container
+Registry, built from the validated release tag:
+
+```bash
+docker pull ghcr.io/dipeshbabu/agentloop:0.2.7
+```
+
+The image runs as a non-root user. Its default command starts the API on port
+8000; the dashboard uses the same image with a `streamlit run dashboard/app.py`
+command. Images are built for `linux/amd64`. Pin an exact version in
+deployments; `latest` follows the newest release.
+
+## Option 1: one server on any cloud
+
+This is the recommended starting point. It works on any Linux virtual machine,
+such as an AWS EC2 instance, a Google Compute Engine VM, an Azure VM or a
+DigitalOcean droplet, and it is the setup CI runs on every change.
+
+The `deploy/` directory contains the stack:
+
+- `deploy/docker-compose.yml` starts Postgres, the API, the dashboard and
+ [Caddy](https://caddyserver.com/), which obtains and renews HTTPS
+ certificates automatically;
+- `deploy/Caddyfile` serves the API on one hostname and the dashboard on
+ another, with a login in front of the dashboard;
+- `deploy/.env.example` lists every setting.
+
+Only ports 80 and 443 are published. The API, dashboard and database are
+reachable only through Caddy or the private Compose network.
+
+### Prepare the server
+
+1. Create a Linux VM and install Docker Engine with the Compose plugin.
+2. Allow inbound TCP 80 and 443 (and UDP 443 for HTTP/3) in the cloud
+ firewall or security group. Keep SSH restricted to your own addresses.
+3. Create DNS records for two hostnames, for example
+ `agentloop-api.example.com` and `agentloop.example.com`, pointing at the VM's
+ public address. Caddy can only issue certificates once these resolve.
+
+### Configure and start
+
+```bash
+git clone --depth 1 --branch v0.2.7 https://github.com/dipeshbabu/agentloop.git
+cd agentloop
+cp deploy/.env.example deploy/.env
+```
+
+Create the dashboard password hash and random secrets:
+
+```bash
+docker run --rm caddy:2 caddy hash-password --plaintext 'choose-a-strong-password'
+openssl rand -hex 32
+```
+
+Edit `deploy/.env`: set `AGENTLOOP_IMAGE` to the release you want, both
+domains, `AGENTLOOP_ADMIN_API_KEY`, `POSTGRES_PASSWORD`, the dashboard user and
+the bcrypt hash. Keep the hash in single quotes so Compose does not expand its
+`$` characters. Never commit `deploy/.env`.
+
+```bash
+docker compose -f deploy/docker-compose.yml up --detach
+docker compose -f deploy/docker-compose.yml ps
+curl https://agentloop-api.example.com/v1/readyz
+```
+
+Open the dashboard hostname in a browser and sign in with the user and password
+you chose.
+
+### Create a project key and upload traces
+
+The admin key only creates project keys. Create one per team or CI pipeline:
+
+```bash
+curl -X POST https://agentloop-api.example.com/v1/api-keys \
+ -H "X-AgentLoop-Admin-Key: $AGENTLOOP_ADMIN_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"project_id": "my-team", "name": "ci"}'
+```
+
+Use the returned key from Python:
+
+```python
+from agentloop import AgentLoopClient
+
+client = AgentLoopClient(base_url="https://agentloop-api.example.com", api_key="...")
+client.upload_trace(trace)
+```
+
+or from the TypeScript SDK with
+`new AgentLoopClient({ baseUrl: "https://agentloop-api.example.com", apiKey: "..." })`.
+In the dashboard, set the sidebar's Project field to the same project ID.
+
+### Upgrade and back up
+
+Back up the database, change `AGENTLOOP_IMAGE` to the new version, then
+recreate the containers. Pending migrations run on startup.
+
+```bash
+docker compose -f deploy/docker-compose.yml exec db \
+ pg_dump --format=custom --username agentloop --file /tmp/agentloop.dump agentloop
+docker compose -f deploy/docker-compose.yml cp db:/tmp/agentloop.dump ./agentloop.dump
+docker compose -f deploy/docker-compose.yml pull
+docker compose -f deploy/docker-compose.yml up --detach
+```
+
+Copy backups off the server and test restoring them. Migrations are
+forward-only; to roll back, restore the backup and redeploy the previous image.
+See [database schema migrations](PRODUCTION.md#database-schema-migrations).
+
+### What CI verifies
+
+Every pull request starts this exact stack with the image built from that
+commit, using Caddy's local certificate authority for `*.localhost` names. It
+checks that:
+
+- the API is ready over HTTPS and stores and returns a trace with a project key;
+- plain HTTP redirects to HTTPS, and uploads over the size limit are refused;
+- the dashboard returns 401 without the login or with a wrong password, and
+ loads with the right one;
+- the API, dashboard and database ports are not published on the host.
+
+## Option 2: managed container platforms
+
+Managed platforms run the image without a server to maintain. Pair the API with
+the platform's managed Postgres:
+
+| Platform | Containers | Postgres |
+| --- | --- | --- |
+| Google Cloud | Cloud Run | Cloud SQL for PostgreSQL |
+| AWS | App Runner or ECS on Fargate | Amazon RDS for PostgreSQL |
+| Azure | Container Apps | Azure Database for PostgreSQL |
+| Others | Fly.io, Render, Railway | Their managed Postgres |
+
+These deployments are not exercised in CI. The same image and settings apply:
+
+1. Some platforms pull only from their own registry, for example Cloud Run from
+ Artifact Registry and App Runner from Amazon ECR. Copy the image there:
+
+ ```bash
+ docker pull ghcr.io/dipeshbabu/agentloop:0.2.7
+ docker tag ghcr.io/dipeshbabu/agentloop:0.2.7 REGISTRY/agentloop:0.2.7
+ docker push REGISTRY/agentloop:0.2.7
+ ```
+
+2. Run the API with container port 8000 and its default command, and set:
+
+ ```bash
+ AGENTLOOP_STORE_BACKEND=postgres
+ AGENTLOOP_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/agentloop
+ AGENTLOOP_REQUIRE_API_KEY=true
+ AGENTLOOP_ADMIN_API_KEY=
+ AGENTLOOP_CORS_ORIGINS=https://
+ ```
+
+ Store the secrets in the platform's secret manager rather than plain
+ environment settings, and percent-encode reserved characters in the URL
+ password. Use `/readyz` as the health check path.
+
+3. Optionally run the dashboard as a second service from the same image with
+ the command `streamlit run dashboard/app.py --server.address=0.0.0.0
+ --server.port=8501 --server.headless=true`, the same database settings, and
+ `AGENTLOOP_API_URL` set to the API's URL. The dashboard has no login of its
+ own: put it behind the platform's identity layer, such as Identity-Aware
+ Proxy on Google Cloud or built-in authentication on Azure Container Apps, or
+ keep it on a private network. Do not expose it publicly without one.
+
+Multiple API replicas can share one database; migrations are safe to run
+concurrently. Set the platform's request size limit to match your largest
+trace uploads.
+
+## Kubernetes
+
+No manifests or Helm chart are provided yet. The image, port, health check and
+environment variables above are all a deployment needs; keep the dashboard
+behind an authenticating ingress.
+
+## Security checklist
+
+- Require API keys (`AGENTLOOP_REQUIRE_API_KEY=true`) and keep the admin key
+ out of clients; give each team or pipeline its own project key.
+- Serve only HTTPS, and never expose the dashboard without a login.
+- Keep Postgres off the public internet and back it up.
+- Traces can contain prompts, tool inputs and outputs. Decide what you capture
+ and how long you keep it before sending production data; see
+ [trace retention](TRACE_RETENTION.md).
+
+The [production guide](PRODUCTION.md) covers every setting, health checks and
+password rotation in detail.
diff --git a/docs/PRODUCTION.md b/docs/PRODUCTION.md
index 4e9fdad..9b2b3f9 100644
--- a/docs/PRODUCTION.md
+++ b/docs/PRODUCTION.md
@@ -6,6 +6,10 @@ AgentLoop has three production surfaces:
- API service: receive traces, enforce API keys, store runs, and serve reports.
- Dashboard: inspect traces, usage, optimization plans, and value reports.
+To run the API and dashboard on a cloud server with HTTPS and a dashboard login,
+follow [Deploy to the cloud](CLOUD_DEPLOY.md). This guide covers every setting
+behind that deployment.
+
## Required configuration
Set secrets outside source control and configure the public origins explicitly:
@@ -214,7 +218,8 @@ Migration `0003` (issue #19) only adds indexes and has no data impact.
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.
+configured. From 0.2.7 it also publishes the container image to
+`ghcr.io/dipeshbabu/agentloop`.
## Deployment Notes
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 986f3f6..49e51ee 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -97,6 +97,14 @@ Recover an interrupted tagged release by explicitly dispatching:
gh workflow run release.yml --ref vX.Y.Z
```
+The container image job builds the Dockerfile from the tagged commit, checks that
+the image reports the release version and runs as a non-root user, and pushes
+`ghcr.io/dipeshbabu/agentloop:X.Y.Z` and `:latest` with the workflow's
+`GITHUB_TOKEN`. GitHub creates the package as private on its first push. Once,
+open the package's settings under the owner's **Packages** tab, connect it to
+this repository if needed, and set its visibility to public so deployments can
+pull it without credentials.
+
Do not reuse a published version or move its tag. Publish a new patch for a fix.
PyPI cannot restore deleted releases or accept a previously used filename.
@@ -121,6 +129,13 @@ path/to/wheel-env/bin/python -I scripts/smoke_installed_wheel.py --expected-vers
On Windows use `path/to/wheel-env/Scripts/python.exe`. A merged PR, tag, or GitHub
release does not prove PyPI publication; verify each destination independently.
+Check the container image the same way:
+
+```bash
+docker pull ghcr.io/dipeshbabu/agentloop:X.Y.Z
+docker run --rm ghcr.io/dipeshbabu/agentloop:X.Y.Z python -c "import agentloop; print(agentloop.__version__)"
+```
+
For the initial numbering restart, install the exact `0.1.0` version in existing
environments and refresh pinned requirements. Removing earlier PyPI releases
requires the owner's [project management page](https://pypi.org/manage/project/agentloop-profiler/releases/).
diff --git a/mkdocs.yml b/mkdocs.yml
index bd1de78..dc197e2 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -123,6 +123,7 @@ nav:
- Workflow tracing: WORKFLOW_TRACING.md
- Dashboard: DASHBOARD.md
- Server deployment: PRODUCTION.md
+ - Deploy to the cloud: CLOUD_DEPLOY.md
- Operations: OPERATIONS.md
- Advanced runtime controls:
- Harness overview: HARNESS.md