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.

Kubernetes environment

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=[email protected]: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 its 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.

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.

Deployment kubeconfig

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

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

Namespace

Production uses:

NAMESPACE=agent-farm

Staging uses:

NAMESPACE=agent-farm-staging

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

The Agent Barn API needs Kubernetes access to manage Agent resources. When POD_KUBECONFIG_B64 is omitted, deploy.sh base64-encodes the deployment kubeconfig:

POD_KUBECONFIG_B64=

For production, supply a dedicated namespace-scoped kubeconfig instead of reusing a cluster-administrator identity. 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.

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=[email protected]

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: [email protected]
Staging:    [email protected]

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

Agent runtimes push Conversations and Tool Calls to the Ingest API. It runs from the API image as a separate FastAPI application, listens on port 8001, and authenticates each Agent with a per-start Ingest key.

The default Kubernetes address is:

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

Local Agent pods use:

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

A broken Ingest path does not necessarily stop an Agent from replying. Instead, Activity can stay empty even though the Agent is working. Make sure Agent pods can reach both services in Kubernetes:

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

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 metrics, Ingest API metrics, LiteLLM metrics, 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.