Deploy Agent Barn to Kubernetes

Confirm that kubectl is connected to the intended cluster:

kubectl config current-context
kubectl cluster-info
kubectl get nodes

Check the required cluster services:

kubectl get ingressclass traefik
kubectl get clusterissuer letsencrypt-http01
kubectl get storageclass

Check whether your deployment identity can create and manage resources:

kubectl auth can-i create namespaces
kubectl auth can-i create deployments --namespace agent-farm
kubectl auth can-i create services --namespace agent-farm
kubectl auth can-i create secrets --namespace agent-farm
kubectl auth can-i create persistentvolumeclaims --namespace agent-farm
kubectl auth can-i create ingresses --namespace agent-farm

These examples cover selected permissions; they are not a complete permission checklist for the bootstrap manifest and Helm releases.

Before running deploy.sh, ask your cluster administrator to confirm that the deployment identity can apply the namespace and RBAC resources in k8s/agent-farm-user.yaml, as well as install the Helm releases. The script attempts this bootstrap apply on every run, even when the resources already exist. Creating the namespace in advance does not make a restricted deployment identity sufficient. If your identity cannot perform that step, arrange the deployment with your cluster administrator before continuing.

Download the release source

Recommended

1. Open Agent Barn releases and select the release you intend to install.
2. Read its release notes, then download Source code (zip) or Source code (tar.gz) from the release assets.
3. Extract the archive into a new directory and open the extracted repository directory in your terminal. Use the directory created by your extraction tool; its name is not necessarily agent-barn-deploy.
4. Copy .env.deploy.spec to .env.deploy, then fill in the deployment settings described in Deployment configuration.

The source archive contains application source and deployment definitions. It does not contain built container images. Before deploying, obtain a compatible image set and any required registry credentials, or build and publish images through a separately documented process for your release.

As of September 5, 2026, v0.16.1 and v0.16.2 provide source downloads but have no separate deployment bundle attached. Older releases contain agent-farm-named bundles; do not use one as a substitute for the deployment files of a newer release.

If your release includes a deployment bundle

This section applies only when a separate deployment bundle has been provided as an additional asset alongside the source download. Skip it if your release has only source archives.

In a terminal with tar available, open the directory containing the download. Replace the example tag with the tag you selected:

RELEASE_TAG='vX.Y.Z'
tar -xzf "agent-barn-deploy-${RELEASE_TAG}.tar.gz"
cd agent-barn-deploy

A bundle extracts to an agent-barn-deploy directory containing deployment charts, Kubernetes prerequisites, helmfile.yaml.gotmpl, deploy.sh, and a generated .env.deploy. Edit that included .env.deploy; you do not need to create it from a spec file when using a bundle.

Keep the extracted files together and run subsequent bundle commands from this directory. The archive contains deployment files, not the container images themselves.

Obtain access to the container images

The deployment needs API, UI, Hermes, and OpenClaw images.

Container image access is separate from source downloads. You need the repository names, version tags, and any required credentials for the registry you will use. If these have not been provided for your installation, resolve image distribution before running the deployment.

Public access to Agent Barn's source code does not grant access to a container registry. Use credentials for the registry named in your deployment configuration; a GitHub token is not a substitute for those credentials.

Before continuing, you need:

A generated deployment bundle, where one is provided, uses clients.registry.k8s.aai-labs.com as its registry host and clients.registry.k8s.aai-labs.com/agent-barn as its image prefix, with repository names api, ui, hermes-base, and openclaw-base. These values describe that distribution; they do not establish that your account has access.

Keep the supplied version tags unless you are deliberately selecting another compatible image set. API and UI use the product release tag. Hermes and OpenClaw have separate runtime version tags; do not give every component the product tag.

If you do not yet have image access, obtain it before running the deployment. Changing the hostname to a different Agent Barn registry does not make the same repositories or tags available there.

Deploy from a Git checkout

Instead of a release archive, you can use the deployment files directly from a checkout of the public repository:

git clone https://github.com/aai-labs/agent-barn.git
cd agent-barn
git checkout RELEASE_TAG
cp .env.deploy.spec .env.deploy

Use a released tag or a commit whose API, UI, Hermes, and OpenClaw image tags are available in your registry.

Open .env.deploy in a text editor and replace every required blank value.

The file is sourced as a shell environment file. Use plain KEY=value entries and avoid spaces around the equals sign.

Cluster and namespace

Set the deployment and API kubeconfigs

1. Obtain the deployment kubeconfig and the API workload kubeconfig from your cluster administrator. Confirm which installation and namespace each is intended for.
2. In .env.deploy, set KUBECONFIG to the deployment kubeconfig's path on the machine where you will run deployment tools.
3. Encode the administrator-supplied API kubeconfig as a single line. In the following command, replace /path/to/agentbarn-api.kubeconfig with that file's actual path:

base64 < /path/to/agentbarn-api.kubeconfig | tr -d '\n'

4. Copy the complete output into POD_KUBECONFIG_B64 in .env.deploy. This value contains Kubernetes credentials; keep it with your deployment secrets and do not paste it into support messages.
5. Keep the credential's expiry and renewal instructions with the installation records. When it changes, update POD_KUBECONFIG_B64 and roll the API through your deployment process so it loads the new credential.

If POD_KUBECONFIG_B64 is missing or empty, the current deploy.sh encodes and uses the deployment kubeconfig for the API. It does not create a separate restricted identity. Base64 encoding changes the representation of a credential, not its permissions.

Use an absolute kubeconfig path:

KUBECONFIG=/home/your-user/.kube/agent-barn-production.yaml
NAMESPACE=agent-farm
STORAGE_CLASS=REPLACE_WITH_STORAGE_CLASS

Container registry

If you downloaded a release bundle, the registry paths and image tags are already populated. Add the registry username and password for your image access without changing the pinned versions. See Obtain access to the container images for what you need and where to get it.

A GitHub token is not required to read the public agent-barn or aai-cli repositories. Kubernetes only needs credentials for the registry from which it pulls the deployment images.

Database configuration

Agent Barn deploys three independent PostgreSQL instances:

Generate independent passwords:

openssl rand -hex 24
openssl rand -hex 24
openssl rand -hex 24

Store these values in your secret manager before deploying.

LiteLLM and OpenRouter

Generate a LiteLLM master key:

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

Keep this key stable. LiteLLM uses it when managing the virtual keys assigned to Agents.

Agent Barn application secrets

Generate the signing key:

openssl rand -hex 32

Generate the Fernet-compatible encryption key:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '\n'

Generate the Firecrawl key:

openssl rand -hex 24

Configure the administrator and environment:

PLATFORM_ADMIN_CREDENTIALS=admin@example.com:REPLACE_WITH_STRONG_PASSWORD
ENVIRONMENT=production

The administrator password must contain at least eight characters, including an uppercase letter, a lowercase letter, and a digit.

Communications values and shared configuration

communications:
  enabled: true
  replicaCount: 1
  service:
    port: 8002
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 512Mi
      cpu: 500m

• communications.enabled controls rendering of the Communications Deployment and Service.
• communications.replicaCount controls process replicas.
• communications.service.port controls the ClusterIP Service port; the container target port remains 8002.
• Communications resource requests and limits are independent of the Product API container. It uses the chart’s API_IMAGE_TAG; there is no separate Communications image repository or tag.

The chart renders <release-name>-communications as both Deployment and ClusterIP Service. Its pod runs uvicorn api.communications_main:app --host 0.0.0.0 --port 8002 with app.kubernetes.io/component: communications. It uses the API release ServiceAccount and image pull Secrets, loads common application settings from the API Secret, connects to the shared PostgreSQL database, uses the shared Agent token encryption key, and starts the ingress supervisor and outbound Delivery worker during its lifespan.

The shared Secret includes DB_CONNECTION_URL, AGENT_TOKEN_ENCRYPTION_KEY, environment identity, common application settings, and provider-specific global settings where configured. Product API and Communications must use the same database and a key consistent across both workloads and all replicas. Connection credentials remain encrypted in PostgreSQL; provider credentials do not belong in Deployment manifests, release environment files, or Agent Runtime pods.

Public hostnames

Configure hostnames without URL schemes in the *_HOST values:

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

Monitoring

The current Helmfile requires:

Add these entries to .env.deploy if they are not already present:

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

Optional email delivery

Leave all three values empty to disable transactional email:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
SENDER_EMAIL=

To enable it:

• Create or select a Cloudflare Email Sending account.
• Verify the sending domain.
• Give the API token the Email Sending: Edit permission.
• Set SENDER_EMAIL to an address on the verified domain.

Use an environment-specific mail. subdomain, such as:

SENDER_EMAIL=noreply@mail.agentbarn.example.com

All three values must be configured for delivery to be enabled.

Optional Google Workspace authentication

Leave these values empty to disable Google OAuth:

GOOGLE_CLOUD_CLIENT_ID=
GOOGLE_CLOUD_CLIENT_SECRET=

To enable it, create a Google OAuth 2.0 Web application client and register this redirect URI:

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

Then set the client ID and client secret in .env.deploy.

Point the following DNS records to the public address of your Traefik ingress controller:

1. UI_HOST
2. API_HOST
3. GRAFANA_HOST

Find the ingress address using the command appropriate for your cluster. For example:

kubectl get services --all-namespaces
kubectl get ingressclass traefik

Confirm that DNS resolves before deploying:

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

Confirm that the expected ClusterIssuer is ready:

kubectl get clusterissuer letsencrypt-http01
kubectl describe clusterissuer letsencrypt-http01

The Product API remains exposed at /api. The only public webhook prefix is /communications/v1/webhooks, routed to <release-name>-api:8000. Keep Runtime Delivery claim, reply, and completion routes, Platform Driver events, /health, and /metrics internal.

Webhook-based Platform Connections receive URLs shaped like https://<api-host>/communications/v1/webhooks/<connection-id>. Public DNS, valid TLS, provider-to-ingress network access, ingress routing, and the correct API_EXTERNAL_URL are required. Microsoft Teams currently uses authenticated webhook ingress; the Connection ID scopes the endpoint and the Platform Plugin authenticates the provider request. A public endpoint must never bypass provider authentication.

Build the pinned monitoring chart dependencies:

helm dependency build helm/monitoring

Review the active Kubernetes context one final time:

kubectl config current-context

Deploy the stack:

./deploy.sh

The script:

1. Loads values from .env.deploy.
2. Verifies that helmfile and kubectl are available.
3. Derives the API pod kubeconfig when POD_KUBECONFIG_B64 is not supplied.
4. Applies the agent-farm namespace and bootstrap RBAC manifest.
5. Runs helmfile sync --wait.
6. Applies database migrations through an API chart hook.
7. Generates the LiteLLM API key used by Agent Barn.
8. Waits for the Helm releases to become ready.

Helmfile deploys agentbarn-api after its supporting application PostgreSQL, LiteLLM, Firecrawl, and Redis releases. Communications is rendered by agentbarn-api, not as a separate Helmfile release. PostgreSQL must be ready before it processes durable data; Redis is not the Communication Delivery queue. Product, Ingest, and Communications use one API image version supplied by API_IMAGE_TAG.

The releases are installed in dependency order:

Communication Connection, Delivery, journal, and Conversation schema changes use the normal API Alembic migrations. The migration hook runs before install or upgrade; wait for it to complete before evaluating Communications health. Do not run a newer Communications process against an older database schema, and do not add a separate Communications migration command.

• Helm releases are installed.
• Workloads become ready.
• Persistent volume claims are bound.
• Ingress and certificate resources are ready.
• The public API and web application respond.

Check the Helm releases:

helm list --namespace agent-farm

Check the workloads:

kubectl get deployments,statefulsets,pods --namespace agent-farm

Check persistent volumes:

kubectl get pvc --namespace agent-farm

Check ingress and certificate resources:

kubectl get ingress --namespace agent-farm
kubectl get certificate --namespace agent-farm
kubectl get certificaterequest --namespace agent-farm

Expected: All long-running pods eventually report Running, and their ready-container counts are complete.

Verify the public API:

curl --fail https://api.agentbarn.example.com/api/v1/health

A healthy response resembles:

{
  "status": "ok",
  "db": "connected"
}

Verify the web application:

curl --head https://agentbarn.example.com

Open these URLs in a browser:

https://agentbarn.example.com
https://grafana.agentbarn.example.com

Verify Communications

Use the namespace and release name for the environment you deployed:

kubectl -n <namespace> get deployment <release-name>-communications

kubectl -n <namespace> rollout status deployment/<release-name>-communications

kubectl -n <namespace> get service <release-name>-communications

kubectl -n <namespace> get pods \
  -l app.kubernetes.io/component=communications

kubectl -n <namespace> logs \
  deployment/<release-name>-communications

Port-forward the internal Service to inspect process availability and the Prometheus surface:

kubectl -n <namespace> port-forward \
  service/<release-name>-communications 8002:8002

curl http://127.0.0.1:8002/health
curl http://127.0.0.1:8002/metrics

/health checks process availability and /metrics confirms that the metrics endpoint is exposed, not that Prometheus is collecting from it. Neither proves PostgreSQL Delivery progress, Runtime claim health, provider connectivity, individual Connection health, or successful outbound provider delivery. Use Communication diagnostics and metrics for those checks; do not expose either endpoint publicly.

Agent Runtime pods must resolve <release-name>-communications and reach http://<release-name>-communications:8002/communications/v1, sending the Runtime Communications bearer credential and protocol-version header. DNS or connection failures indicate cluster networking or Service configuration; 401 Unauthorized indicates a credential problem, 426 Upgrade Required a protocol-version mismatch, and 204 No Content from a valid claim request means no Delivery is pending. Do not put a Runtime bearer credential in this guide.

Confirm public DNS and valid TLS route /communications/v1/webhooks/* and /api/* to Product API. Confirm /communications/v1/agents/* and /metrics are not public. An unauthenticated webhook request should be rejected, not treated as a functional message test; validate the complete webhook through the intended provider’s setup flow.

If a pod is not ready, inspect it before retrying the deployment:

kubectl describe pod POD_NAME --namespace agent-farm
kubectl logs POD_NAME --namespace agent-farm

Sign in at WEB_APP_URL using the address and password from PLATFORM_ADMIN_CREDENTIALS.

A fresh Agent Barn database contains the platform administrator but no Organization. Complete the initial setup in this order:

1. Sign in as the platform administrator.
2. Create an Organization.
3. Add or invite Organization members.
4. Configure shared credentials and integrations.
5. Hire an Agent from a predefined template.
6. Configure its Communication Connections and model.
7. Start the Agent.

After starting the first Agent, verify that Kubernetes created its resources:

kubectl get deployments,pods,services,pvc \
  --namespace agent-farm \
  --selector agentbarn.io/component=agent

Each Agent receives a 1 GiB PVC by default. Its generated resources remain isolated by Agent identity within the agent-farm namespace.

Complete a Communications check

1. Confirm Product, Ingest, and Communications workloads are healthy and migrations completed.
2. Create or open a stopped headless Agent, then add one Communication Connection.
3. Confirm the Connection reports provider health independently from Agent lifecycle, then start the Agent.
4. Send a provider message that passes Connection policy and confirm an inbound Conversation Message appears.
5. Confirm the Runtime claims and completes the Delivery, then confirm the outbound reply reaches the same Connection.
6. Review Connection diagnostics for the complete pipeline and confirm Tool Calls still appear through Ingest separately.