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

If your identity cannot create namespaces, ask the cluster administrator to create agent-farm and provision the required namespace-scoped deployment identity before continuing.

Use a release bundle

Recommended

The recommended deployment artifact is the Agent Barn release bundle. It contains:

• The Helm charts
• helmfile.yaml.gotmpl
• Kubernetes bootstrap manifests
• deploy.sh
• A release-specific .env.deploy with compatible image tags

Download the bundle for the release you want to deploy, then extract it:

tar -xzf agent-barn-deploy-RELEASE_TAG.tar.gz
cd agent-barn-deploy

Replace RELEASE_TAG with the release you downloaded.

Deploy from the source repository

You can also use the deployment files directly from 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

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 should already be populated. Add the credentials supplied for that registry without changing the pinned versions.

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

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

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

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.

The releases are installed in dependency order:

• 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

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 chat platform 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.