Configure a self-hosted platform

Local environment

From the repository root:

cp .env.spec .env

Open .env and replace the placeholder values. The full local launcher checks its required values before it creates the cluster or starts containers:

./run.sh

If a required value is missing, the script exits and lists the missing variable names.

For native local development, start Product API, Ingest, and Communications together with make dev-api, or run Communications alone with make dev-communications. The complete ./run.sh Docker stack includes Communications as a separate process. Where local tooling supports it, its default port is:

COMMUNICATIONS_PORT=8002

Kubernetes environment

Open the configuration for your deployment path:

The bundle and repository spec can contain different image repository defaults. Use the values for your chosen image distribution rather than mixing the two configurations.

For bundle discovery and image-access prerequisites, see Deploy to Kubernetes.

For a repository checkout, copy the template from the deployment directory:

cp .env.deploy.spec .env.deploy

Restrict access to the file:

chmod 600 .env.deploy

The file is sourced by a shell, so use plain assignments:

KEY=value

Avoid spaces around =, shell command substitutions, values copied from examples, unescaped shell metacharacters, multiline secret values, and comments placed after a secret on the same line.

Use a secret manager as the authoritative backup. The deployment file is an input, not an adequate recovery system.

Agent Barn requires three stable cryptographic values and one bootstrap administrator credential.

Generate the stable values

Generate the signing key:

openssl rand -hex 32

Generate the Fernet encryption key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Generate the LiteLLM master key:

echo "sk-$(openssl rand -hex 24)"

Add them to the configuration:

SECRET_SIGNING_KEY=REPLACE_WITH_GENERATED_SIGNING_KEY
AGENT_TOKEN_ENCRYPTION_KEY=REPLACE_WITH_GENERATED_FERNET_KEY
LITELLM_MASTER_KEY=sk-REPLACE_WITH_GENERATED_VALUE

Stable-key responsibilities

Configure the bootstrap administrator

PLATFORM_ADMIN_CREDENTIALS=admin@example.com:REPLACE_WITH_STRONG_PASSWORD

The password must contain at least eight characters, an uppercase letter, a lowercase letter, and a digit. Do not use a colon in the password, because the value uses a colon to separate the email from the password.

The bootstrap credential is used only when Agent Barn finds no existing Platform Administrator. Changing the environment variable after the initial bootstrap does not change the existing administrator’s password.

Set the environment label

ENVIRONMENT=production

Use a distinct value such as staging for another stack. The label appears in operational metrics and alerts.

The Kubernetes deployment creates three independent PostgreSQL releases.

Configure each database independently:

POSTGRES_APP_USER=agentfarm
POSTGRES_APP_PASSWORD=REPLACE_WITH_UNIQUE_PASSWORD
POSTGRES_APP_DB=agentfarm

POSTGRES_LITELLM_USER=litellm
POSTGRES_LITELLM_PASSWORD=REPLACE_WITH_DIFFERENT_PASSWORD
POSTGRES_LITELLM_DB=litellm

POSTGRES_FIRECRAWL_USER=firecrawl
POSTGRES_FIRECRAWL_PASSWORD=REPLACE_WITH_ANOTHER_PASSWORD
POSTGRES_FIRECRAWL_DB=firecrawl

Generate URL-safe passwords with:

openssl rand -hex 24

Hex values avoid connection-string escaping problems. Do not reuse one password across all three databases.

Local database URL

Native host commands require an explicit application database URL:

DB_CONNECTION_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${POSTGRES_PORT}/${POSTGRES_DB}

Compose overrides this with the internal db service hostname, and Kubernetes derives the application connection URL from its POSTGRES_APP_* values.

Redis

Redis carries the general background worker and the Event Delivery pipeline:

REDIS_URL=redis://localhost:6379/0

Local Compose replaces the hostname with redis. Kubernetes uses:

redis://redis:6379/0

Redis unavailability does not prevent the Product API from committing supported Domain Events, but low-latency Event Delivery processing stops until the worker and transport recover.

Firecrawl

Generate a platform Firecrawl key with openssl rand -hex 24, then configure it for Kubernetes:

FIRECRAWL_API_KEY=REPLACE_WITH_GENERATED_VALUE

The current deployment uses the same platform key for the self-hosted Firecrawl service and the default Agent integration. Individual Agents can later receive their own credential overrides; see Connect Firecrawl.

Agent Barn sends model requests through LiteLLM, which uses OpenRouter as the configured provider.

Agent runtime
      │
      ▼
LiteLLM proxy
      │
      ▼
OpenRouter

OpenRouter

Set a real OpenRouter inference key:

OPENROUTER_API_KEY=sk-or-REPLACE_WITH_PROVIDER_KEY

OPENROUTER_API_KEY and LITELLM_MASTER_KEY are different credentials:

Default model

Configure the default using the full Agent Barn model path:

AGENT_DEFAULT_MODEL=litellm/openrouter/z-ai/glm-5.2

The segment following litellm/openrouter/ must be a valid OpenRouter model ID.

Model catalogue allowlist

Limit the model picker with comma-separated fnmatch globs:

AGENT_MODEL_ALLOWLIST=z-ai/glm-5.2,openai/gpt-5*

Patterns match OpenRouter model IDs without the litellm/openrouter/ prefix. An empty value exposes the full available catalogue:

AGENT_MODEL_ALLOWLIST=

An Organization can narrow its own allowed models further. The environment allowlist controls what the platform catalogue offers; it does not replace Organization model governance.

Runtime images

Kubernetes deployments use four compatible images:

API_IMAGE_TAG=RELEASE_API_TAG
UI_IMAGE_TAG=RELEASE_UI_TAG
OPENCLAW_IMAGE_TAG=RELEASE_OPENCLAW_TAG
HERMES_IMAGE_TAG=RELEASE_HERMES_TAG

Local development uses full Agent image references:

OPENCLAW_IMAGE=registry.example.com/agentbarn-openclaw-base:RELEASE_TAG
HERMES_IMAGE=registry.example.com/agentbarn-hermes-base:RELEASE_TAG

Kubernetes Agent workloads use OPENCLAW_IMAGE and HERMES_IMAGE. The older AGENT_IMAGE setting is not used by the current API.

Use the runtime image versions supplied with the selected Agent Barn release. Hermes and OpenClaw versions must stay compatible with that release; do not combine an arbitrary API image with unrelated runtime versions.

LiteLLM addresses

In Kubernetes, both the API and the Agents use the in-cluster service:

http://litellm:4000

In local k3d, the API container reaches LiteLLM through the Compose network, while Agent pods reach the host-published proxy through host.docker.internal on default port 7070:

AGENT_LITELLM_BASE_URL=http://host.docker.internal:7070

Running Agents keep their current pod image and generated configuration until they are stopped and started again.

A Kubernetes deployment uses separate UI, API, and Grafana hostnames:

UI_HOST=agentbarn.example.com
API_HOST=api.agentbarn.example.com
GRAFANA_HOST=grafana.agentbarn.example.com
WEB_APP_URL=https://agentbarn.example.com

Use hostnames without a scheme for UI_HOST, API_HOST, and GRAFANA_HOST, and the complete public origin for WEB_APP_URL. The API chart derives API_EXTERNAL_URL from the first configured API hostname.

DNS

Point all three hostnames at the public address of the Traefik ingress controller, then verify resolution before deploying:

dig +short agentbarn.example.com
dig +short api.agentbarn.example.com
dig +short grafana.agentbarn.example.com

Ingress exposure

The UI ingress exposes /. The API ingress exposes only:

/api

The API ingress deliberately does not expose /metrics, the Ingest API port, or internal worker endpoints. Prometheus scrapes metrics through Kubernetes Services, and Agent Runtimes send telemetry to the in-cluster Ingest service rather than a public ingress.

API_EXTERNAL_URL is the public Agent Barn origin used to construct provider webhook URLs. A saved webhook-based Connection receives a URL shaped like:

https://<public-host>/communications/v1/webhooks/<connection-id>

The origin must use valid public HTTPS for providers such as Microsoft Teams, and public DNS must resolve to the deployment ingress. Route only /communications/v1/webhooks to Communications; this is not the internal Runtime Communications URL, and the webhook URL contains no provider credential.

TLS

The API and UI charts currently use this cert-manager ClusterIssuer:

letsencrypt-http01

Confirm that it exists:

kubectl get clusterissuer letsencrypt-http01

HTTP-01 requires publicly reachable DNS and ingress. A private installation needs a certificate strategy compatible with its network.

The hook ServiceAccount and the API's mounted kubeconfig serve different purposes. Creating agent-farm-user does not create or export the API kubeconfig. See Deploy to Kubernetes for the access preparation and encoding steps.

Deployment kubeconfig

Set the kubeconfig used by kubectl, Helm, and Helmfile, using an absolute path:

KUBECONFIG=/absolute/path/to/agent-barn-production.yaml

KUBECONFIG is the path to the kubeconfig used by deployment tools on the deployment machine. With the supplied deploy.sh, its identity must also be able to perform the script's bootstrap apply.

Namespace

Production uses:

NAMESPACE=agent-farm

Staging uses:

NAMESPACE=agent-farm-staging

NAMESPACE is the namespace for the Helmfile releases, defaulting to agent-farm. Bootstrap resources and workload permissions must match; changing this value alone does not adapt the shipped bootstrap manifest.

The API chart sets K8S_NAMESPACE from the Helm release namespace, which prevents a staging API from creating Agent workloads in production.

API-facing kubeconfig

POD_KUBECONFIG_B64 is the single-line base64 encoding of the kubeconfig the API uses to manage Agent workloads:

POD_KUBECONFIG_B64=

Supply a separately authorized workload identity when required by your deployment policy. A missing or empty value falls back to the deployment kubeconfig in deploy.sh; that implementation default is not a statement about your installation's security requirements.

That identity needs to manage Deployments, Services, ConfigMaps, Secrets, PersistentVolumeClaims, Pods, Pod logs, and the exec and port-forward operations the health and log workflows use.

For the deployed API, use a kubeconfig for the installation's cluster. When running inside Kubernetes, the client can rewrite the configured server address to the in-cluster API endpoint; supplying another cluster's kubeconfig is not a supported way to redirect this deployment path.

When rotating this credential, update the deployment configuration and roll the API through the deployment process. The client caches its Kubernetes configuration, so replacing a mounted file alone should not be treated as a live credential reload. A token copied into a static kubeconfig does not automatically renew itself.

Container registry

REGISTRY_PREFIX=registry.example.com/agent-barn
REGISTRY_SERVER=registry.example.com
REGISTRY_USERNAME=REPLACE_WITH_USERNAME
REGISTRY_PASSWORD=REPLACE_WITH_ACCESS_TOKEN

API_IMAGE_REPOSITORY=api
UI_IMAGE_REPOSITORY=ui
HERMES_IMAGE_REPOSITORY=hermes-base
OPENCLAW_IMAGE_REPOSITORY=openclaw-base

REGISTRY_PREFIX is prepended to image repository names, and REGISTRY_SERVER identifies the registry for authentication.

Storage

Select a StorageClass, or leave it empty to use the cluster default:

STORAGE_CLASS=REPLACE_WITH_STORAGE_CLASS

The StorageClass is used by the application, LiteLLM, and Firecrawl PostgreSQL releases, by Prometheus, and by generated Agent PVCs. Use network-replicated storage when node-loss durability is required.

Transactional email

Agent Barn uses Cloudflare Email Sending for invitations, password recovery, and Agent lifecycle notifications. Email is enabled only when all three values are set:

CLOUDFLARE_ACCOUNT_ID=REPLACE_WITH_ACCOUNT_ID
CLOUDFLARE_API_TOKEN=REPLACE_WITH_EMAIL_SENDING_TOKEN
SENDER_EMAIL=noreply@mail.agentbarn.example.com

The Cloudflare token needs Email Sending: Edit permission, and the SENDER_EMAIL domain must be verified for Email Sending. Use a separate mail.-style subdomain per environment:

Production: noreply@mail.agentbarn.example.com
Staging:    noreply@mail-staging.agentbarn.example.com

To disable delivery, leave all three empty:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
SENDER_EMAIL=

With delivery disabled, send attempts are logged and treated as no-ops. Avoid configuring only one or two values, because the platform still considers email disabled.

Google Workspace OAuth

Create a Google OAuth 2.0 Web application client and register this redirect URI:

https://agentbarn.example.com/api/v1/integrations/google/callback

Then configure the client values:

GOOGLE_CLOUD_CLIENT_ID=REPLACE_WITH_CLIENT_ID
GOOGLE_CLOUD_CLIENT_SECRET=REPLACE_WITH_CLIENT_SECRET

Google OAuth is enabled only when both values are set and the callback matches <WEB_APP_URL>/api/v1/integrations/google/callback exactly. Leave both empty to disable it.

These are application-owned OAuth client credentials. The refresh token created when a user connects Google Workspace remains Agent-specific and encrypted by Agent Barn; see Connect Google Workspace.

Event Delivery worker

The Kubernetes API chart deploys a general Dramatiq worker and a scheduled Event Delivery reconciliation CronJob. Both use Redis. The default reconciliation schedule is:

*/5 * * * *

Local development uses:

make redis-up
make dev-worker

A one-shot local reconciliation pass is available through:

make reconcile

Ingest API

Ingest is a separate FastAPI application on port 8001. INGEST_BASE_URL is the internal endpoint used only for Runtime Tool Call telemetry, authenticated with a per-start Ingest key. Its value must end in /ingest/v1.

The default Kubernetes address is:

INGEST_BASE_URL=http://agentbarn-api:8001/ingest/v1

Local Agent pods use:

INGEST_BASE_URL=http://host.docker.internal:8001/ingest/v1

Do not use Ingest for Conversation Messages, provider events, Communication Deliveries, Runtime replies, or platform routing.

Communications service

COMMUNICATIONS_BASE_URL is the internal base URL supplied to Agent Runtimes for the versioned Communications protocol. It must end in /communications/v1; prefer the internal Service whenever it is available.

COMMUNICATIONS_BASE_URL=http://host.docker.internal:8002/communications/v1

COMMUNICATIONS_BASE_URL=http://agentbarn-api-communications:8002/communications/v1

The exact Kubernetes hostname depends on the Helm release name. Runtime communication uses a separate per-start Communications credential and protocol version; it is not interchangeable with the Ingest credential.

Make sure Agent pods can reach both internal services in Kubernetes:

LiteLLM: http://litellm:4000
Ingest:  http://agentbarn-api:8001/ingest/v1
Communications: http://agentbarn-api-communications:8002/communications/v1

Communications uses the shared application database and these process environment variables:

COMMUNICATION_JOURNAL_RETENTION_DAYS accepts values from 1 through 3650. If the Helm chart does not expose a dedicated value for an optional setting, configure it as a process environment variable instead of inventing chart behavior.

The development and test controls SKIP_SLACK_TOKEN_VALIDATION, SKIP_TELEGRAM_TOKEN_VALIDATION, SKIP_DISCORD_TOKEN_VALIDATION, and SKIP_TEAMS_TOKEN_VALIDATION default to false and bypass external credential validation. Use them only in controlled development or test environments; they must remain disabled in production and do not make invalid credentials usable.

Communications in Kubernetes

communications:
  enabled: true
  replicaCount: 1
  service:
    port: 8002

The API chart creates a separate Communications Deployment and ClusterIP Service. Product API receives the internal Communications Service URL, while the Communications pod reads shared application configuration from the API Secret. Readiness and liveness use /health on port 8002; /metrics remains internal. Disabling Communications does not leave Platform messaging functional.

Increasing communications.replicaCount is supported by PostgreSQL-backed Connection ingress leases. One replica supervises a given provider Connection at a time, durable Deliveries remain in PostgreSQL, and Connection revision changes trigger provider-session reconciliation. Every replica shares the database and encryption configuration; webhook requests may be load-balanced across replicas. Do not run independent Communications replicas against separate databases.

Communication Deliveries are durable PostgreSQL records. Provider ingress and outbound processing do not use the Domain Event Dramatiq queue as their source of truth; Redis remains for the general worker and Domain Event delivery.

The current Helmfile deploys Prometheus, Grafana, Alertmanager, kube-state-metrics, and the Agent Barn dashboards and alert rules.

Add the following variables to .env.deploy:

SLACK_ALERTS_WEBHOOK_URL=REPLACE_WITH_ALERT_WEBHOOK
GRAFANA_ADMIN_PASSWORD=REPLACE_WITH_STRONG_PASSWORD
GRAFANA_HOST=grafana.agentbarn.example.com

Build the chart dependencies before deployment:

helm dependency build helm/monitoring

The monitoring stack is namespace-scoped and does not create its own cluster-scoped RBAC.

Prometheus reads Product API, Ingest API, Communications, LiteLLM, and Agent health metrics, Kubernetes state for the release namespace, and the remaining OpenRouter credits when the provider key has a configured credit limit.

Grafana is the only monitoring component exposed through ingress. Use a dedicated Slack webhook, and restrict access to the Grafana administrator password.

Communications exposes these internal endpoints:

GET http://<communications-host>:8002/health
GET http://<communications-host>:8002/metrics

/health is a process-level liveness and readiness response; it does not summarize every Connection. /metrics exports HTTP and low-cardinality Communications metrics. Use Communication diagnostics for per-Connection investigation. Neither endpoint should be public.