Local Development, Operations, and Releases

The tag input supplies API/UI image versions. Runtime image versions come from their corresponding VERSION files. Registry configuration uses CLIENT_REGISTRY_URL, CLIENT_REGISTRY_USERNAME, and CLIENT_REGISTRY_PASSWORD. Images are named <client-registry>/agent-barn/<component> and receive the resolved version tag and a moving latest tag.

The UI build uses NEXT_PUBLIC_BACKEND_URL=http://agentbarn-api:8000 for its in-cluster backend. This assumes the corresponding Service and namespace/network topology; it is not a browser-facing public API URL or an automatic fit for every custom deployment.

A client image publication and a hosted cluster deployment are different operations. Choose deployment image references deliberately rather than treating latest as an immutable release identifier.

Local services are the web app on 3000 at /, Product API on 8000 at /api/v1, Ingest API on 8001 at /ingest/v1, Communications on 8002 at /communications/v1, LiteLLM on 7070, PostgreSQL on 5432, and Redis on 6379.

make dev-api starts the Product API, Ingest API, and Communications process together without making Ingest or Communications part of the Product API boundary. Use make dev-ingest for the telemetry sink alone, make dev-communications for the Communications application alone, make dev-ui for Next.js, and make dev-worker for Dramatiq. make run delegates to the complete Docker and local Kubernetes workflow.

./run.sh runs PostgreSQL, Redis, Product API, Ingest, worker, Communications, UI, and local k3d; ./stop.sh stops the full environment, while ./stop.sh --clean also removes the local k3d cluster. Use make restart-ui after adding an App Router directory so the Docker UI route manifest refreshes.

Local Agent pods use INGEST_BASE_URL=http://host.docker.internal:8001/ingest/v1 and COMMUNICATIONS_BASE_URL=http://host.docker.internal:8002/communications/v1; Kubernetes deployments use namespace-local internal Services instead.

Communications is separately served with its own ingress supervision and outbound Delivery loop. Its durable Connection, Delivery, Conversation, and operation-journal records share the application database, so schema changes use the common Alembic sequence. The content-free operation journal is retained for COMMUNICATION_JOURNAL_RETENTION_DAYS, defaulting to 31 days with an allowed range of 1 through 3650; the Communications supervisor prunes it. Retention is operational configuration, not a chart or application version change.

make setup, make db-up, make dev-api, make dev-communications, make dev-ingest, make dev-ui, and make dev-worker establish focused local workflows.

make run, make restart-ui, make migrate, make merge-heads, make rollback, and make makemigrations cover complete startup, UI routes, and migration lifecycle.

If you are deploying Agent Barn for your own team, start with /guides/self-hosting/configure-production and use your own infrastructure values.

The k3s branch deployment workflows and the Talos public release workflow are separate AAI Labs environments. Their PUBLIC_* and STAGING_* settings, storage classes, hostnames, and account-sharing arrangements apply to those workflows.

The hosted-environments, staging-hook-identity, staging-isolation, email-operations, and versioning-and-deployment sections that follow describe those company environments. Independent installations should read them as examples rather than as requirements.

.github/workflows/deploy.yml deploys the k3s testing environments from staging and main with moving environment tags and branch-specific configuration. The public workflow may also publish latest in the public registry, but deployment remains pinned to the release tag. Chart appVersion is not the source of truth for API or UI deployment images, and documentation-only changes do not require an application image release. See the versioning and deployment section below for the release-tag boundary itself.

Change detection compares with the latest successful deployment on the same branch, and a failed deployment does not advance that baseline. Manual dispatch or an unavailable baseline builds all four Agent Barn images. Branch-group concurrency does not cancel an in-progress deployment when a newer run starts, so two overlapping k3s testing deployments mean a deployment path bypassed that concurrency group; inspect active runs and standardize on deploy.yml. A hosted public release that does not start usually has no matching pushed vX.Y.Z tag, or a manual dispatch selected a tag that does not exist on main.

The public registry registry.agentbarn.dev is configured through PUBLIC_REGISTRY_URL with separate public credentials. The public cluster must not depend on or write to the k3s testing registry.

Public production uses separately managed PUBLIC_* values for PostgreSQL passwords, signing and encryption keys, registry password, LiteLLM master key, Firecrawl key, Platform Administrator credentials, Grafana administrator password, alerting webhook, and OpenRouter key where quota isolation is required. Cloudflare email account/token, Google OAuth application credentials, database usernames and names, model defaults, and allowlist configuration are shared company accounts and may be shared only deliberately. Public-only infrastructure Secrets use the PUBLIC_ prefix; copy testing-cluster passwords or signing keys only through a deliberate, reviewed exception.

Public hostname and storage variables are workflow configuration for these environments: PUBLIC_API_HOST for the public Product API and provider-webhook hostname, PUBLIC_UI_HOST for the hosted web application, PUBLIC_WEB_APP_URL for its full HTTPS URL, PUBLIC_GRAFANA_HOST for product monitoring, PUBLIC_SENDER_EMAIL for the public transactional sender, and PUBLIC_STORAGE_CLASS=rook-ceph-block-main for durable public storage.

Staging: k3s, namespace agent-farm-staging, push to staging through deploy.yml, latest-staging and -staging Runtime versions.

Main testing ground: k3s, namespace agent-farm, push to main through deploy.yml, moving latest tags.

Hosted public production: dedicated Talos cluster, namespace agent-farm, vX.Y.Z tag through deploy-public.yml, API and UI pinned to the release tag.

Testing image tags: API and UI use latest on main and latest-staging on staging; Hermes and OpenClaw use their version-file tag, suffixed -staging on staging.

The current CI workflow selects agent-farm-staging-user for staging, while k8s/agent-farm-user.staging.yaml creates agent-farm-user in agent-farm-staging. The LiteLLM key bootstrap Job runs as the account named by LITELLM_KEY_SERVICE_ACCOUNT, so staging cannot create litellm-api-key while the two names differ. Reconcile the workflow value and the staging bootstrap manifest before the hook runs; this discrepancy is unresolved in the repository, so do not assume a deployment has already corrected it.

References: .github/workflows/deploy.yml, k8s/agent-farm-user.staging.yaml, and k8s/agent-farm-user.yaml.

The Communications Deployment and Service run in the same release namespace as the Product API. Product API and Agent Runtimes receive the namespace-local Communications base URL for that release, and provider webhook ingress routes only /communications/v1/webhooks to the Communications Service.

The staging branch deploys to the staging namespace on the AAI Labs k3s testing cluster; main deploys to the main namespace on that same testing cluster. Neither is hosted public production. Moving latest and latest-staging tags belong only to those branch testing deployments.

The API image contains Product, Ingest, worker, and Communications application code. Helm runs Communications as a separate workload using that image, so Communications needs no separate application version. API and UI tags are explicit deployment inputs; Hermes and OpenClaw retain their own VERSION files. Chart version is packaging-only and changes only when chart templates or values change; documentation-only changes require neither image tags nor chart-version changes.

Public deployment must not reuse k3s registry credentials, signing keys, database passwords, or kubeconfig unless sharing is explicitly intended. Use .github/workflows/deploy.yml, .github/workflows/deploy-public.yml, and docs/adr/2026-08-27-public-cluster-release-tags.md as the release-boundary references.

Low-cardinality Communications metric families cover observed Connection status, inbound and outbound Delivery outcomes, pending queue depth, oldest queued Delivery age, Delivery latency, reconnect requests, and provider admission-policy dispositions. Metrics summarize system behavior; operators use Connection diagnostics and journal views for one Connection or Delivery. Metric failures must never interrupt Communications processing.

Keep labels low-cardinality: never label metrics with Organization, Agent, Connection, Delivery, provider-message, channel, or user IDs, or credential fingerprints. Run make check-monitoring after alert-rule or dashboard changes.

Treat signing and encryption key rotation as migrations, preserve migration and secret-hook behavior and LiteLLM quota-aware rollout, and use deployment workflows instead of manual mutable-tag publishing. Continue with /guides/self-hosting/communications, /guides/self-hosting/configuration, /guides/self-hosting/deploy-kubernetes, /guides/self-hosting/monitoring, /guides/self-hosting/upgrades, and /guides/observe-and-govern/communication-diagnostics for detailed procedures.

agentbarn_communication_connection_status and agentbarn_communication_delivery_outcomes.

agentbarn_communication_queue_depth, agentbarn_communication_oldest_queued_age_seconds, and agentbarn_communication_delivery_latency_seconds.

agentbarn_communication_reconnects and agentbarn_communication_policy_dispositions.