Agent Barn

AI coworkers in Slack, Microsoft Teams, Telegram, and Discord, running on your infrastructure.

Website · Docs · Recipes · Discord

Agent Barn is an open-source control plane for AI agents. Define an agent once, connect it to the tools your team already uses, and run it in your own Kubernetes cluster. No seat licence, no second workspace to check.

• Talk to your tools. Agents live in Slack, Microsoft Teams, Telegram, and Discord.
• A model per agent. Each gets its own virtual key on a LiteLLM proxy in your namespace.
• See what it costs. Per-agent token and spend attribution, not one opaque monthly number.
• Multi-tenant from the start. Organisation roles and per-agent access roles, isolated in the data layer.
• Audit what happened. Conversation history, a tool-call log, and a domain-event trail.
• Self-host it. Helm charts, Helmfile, PostgreSQL, your cluster.

Everything runs in your namespace: the control plane, the database, the model proxy, and one pod per running agent. Outbound traffic goes to OpenRouter through the LiteLLM proxy you operate, and to whichever tool APIs you connect. Credentials are encrypted at rest in your own PostgreSQL.

Contents

• Quick start — before you begin, then six steps to a running agent
• What ships in the box — agents, skills, runtimes
• Capabilities
• Development — native, k3d, migrations, tests, troubleshooting
• Deploying to Kubernetes — connecting agent email
• Repository layout
• Getting help and contributing

Quick start

Start the full local stack — control plane, database, model proxy, and the Kubernetes cluster agents run on — and hire your first agent. The step-by-step version with screenshots is at agentbarn.dev/guides/get-started.

Before you begin

Required software

• Git — used to clone the repository.
• Docker with Compose v2 — everything runs in containers, including the local Kubernetes cluster.
• bash — run.sh and stop.sh are shell scripts. On Windows, see Windows.
• kubectl — used to seed the cluster namespace and secret.
• OpenSSL — used below to generate local keys.
• curl — used by the verification steps.

Python and Node.js are not needed to run the app; they're only for the native dev-* targets, tests, and lint (see Development).

Required credentials

1. An OpenRouter API key — every agent's model calls route through it.

Local ports — these must be free:

Make sure these ports are free before starting the full stack. The configurable ports are identified in .env.spec and the k3d helper scripts.

1. Clone the repository

git clone https://github.com/aai-labs/agent-barn.git
cd agent-barn

2. Create the local configuration

cp .env.spec .env

Now fill in these values. Every option in .env.spec is commented, and anything not listed here has a working local default:

Generate the two keys:

# AGENT_TOKEN_ENCRYPTION_KEY — encrypts platform credentials at rest
openssl rand -base64 32 | tr '+/' '-_'

# LITELLM_MASTER_KEY
echo "sk-$(openssl rand -hex 16)"

[!IMPORTANT] LITELLM_MASTER_KEY must stay stable. LiteLLM encrypts the virtual keys it stores with this value, so changing it later breaks every agent created under the old one.

You don't need to touch API_K8S_KUBECONFIG_PATH — run.sh sets it for you once the cluster is up.

3. Start Agent Barn

./run.sh

This validates .env, brings up the k3d cluster and LiteLLM, builds and loads the agent base images, starts db and redis, runs database migrations, then starts api, worker, communications, and ui with hot reload and follows the logs. Ctrl-C detaches without stopping anything; use ./run.sh --detach to skip the logs entirely.

If a startup value checked by run.sh is missing, the script fails immediately and lists it.

[!NOTE] The first run builds both agent base images from scratch and takes a while. Later runs skip any image tag already present in the cluster.

4. Verify the environment

The API reports its own database connectivity:

curl -s localhost:8000/api/v1/health
# {"status":"ok","db":"connected"}

Then check the UI answers and every container is healthy:

curl -s -o /dev/null -w '%{http_code}\n' localhost:3000   # → 200
docker compose ps                                          # all Up / healthy

Finally, confirm the cluster agents will run on is ready and its namespace was seeded:

export KUBECONFIG=.k3d/kubeconfig-host.yaml
kubectl get nodes            # one Ready node
kubectl get ns agent-farm    # Active

[!NOTE] The namespace is agent-farm, not agent-barn. Kubernetes namespaces were deliberately left unrenamed in the rebrand — moving running workloads would mean recreating every agent Deployment and PVC.

5. Sign in

Open http://localhost:3000 and log in with the email:password you set in PLATFORM_ADMIN_CREDENTIALS.

[!TIP] If the API exited at startup with 500: Error while initializing startup data, that password almost certainly failed the policy check. See Troubleshooting.

6. Create an organisation, then hire an agent

Agents are organisation-scoped and a fresh database has none, so create an organisation first. Then pick a template (see Agents), choose a model, attach any credentials its skills need, and start it. Connecting it to Slack, Teams, Telegram, or Discord is a per-agent Communication Connection; the UI walks through each platform's setup.

Stopping and restarting

make run, make stop, and make stop-clean are thin wrappers around the same scripts. Volumes are never deleted by either script.

What ships in the box

Agents

An agent is a template plus a model, one or more communication connections, and a set of credentialed skills. These templates ship as seeds:

Templates are content, not code: a settings.yaml plus Markdown artifacts (soul, identity, user, tools, agents, boot, bootstrap, heartbeat), with anything a template omits inherited from shared defaults. The seeds in api/domains/templates/predefined/seeds/ bootstrap the platform lineages once; after that, new versions are authored through the platform admin flow, and organisations fork or override them per agent. Details: docs/features/templates-and-skills.md. Each template has a guided setup at agentbarn.dev/recipes.

Skills

Skills are what agents can actually do:

Bitbucket · Confluence · Excel · GitHub · Google Drive · HubSpot · Jira · OpenPanel · Pipedrive · PostHog · Zoho Mail

Each mounts documentation into the agent's workspace and is gated on the credential its provider needs, so an agent only gets a skill once the matching credential is attached. Skills whose credential lifecycle isn't modelled yet (Excel, Google Drive, HubSpot, OpenPanel, PostHog) are attachable but not auto-attached — Excel needs no credential at all, since it works on local files. Agents also reach a self-hosted Firecrawl for web retrieval.

Building one is a contribution we'd welcome. Open a Discussion first so we can tell you if one is already in progress.

Runtimes

Agents run as pods, one per agent, from a pinned base image:

Both consume the same runtime-neutral communications protocol, so every platform works on either runtime. Both are upstream projects; this repository holds the Dockerfiles that pin and extend them, the telemetry plugins they load, and the builders that turn an agent record into Kubernetes resources.

Capabilities

Development

./run.sh is enough for most work. For faster iteration, or to run only part of the stack, use the native path below. The contribution workflow and engineering context routes start in CONTRIBUTING.md.

Native development, tests, and lint additionally need Make, Python 3.14 + uv and Node.js 24 + pnpm 11.17.0, matching the repository and CI pins.

Native (non-Docker) development

Each dev-* service target watches its own source. Run the ones you need in separate terminals, alongside make db-up:

make setup         # uv sync + pnpm install; creates .env from .env.spec if absent
make db-up         # Postgres only
make migrate       # apply migrations
make dev-api       # API on :8000; also starts Ingest :8001 and Communications :8002
make dev-ui        # UI on :3000, hot reload
make dev-worker    # Dramatiq worker, hot reload
make dev-ingest    # Ingest only (normally started by dev-api)
make dev-communications  # Communications only (normally started by dev-api)
make reconcile     # one-shot repair pass for stuck/unpublished deliveries

make db-down stops PostgreSQL; make db-logs and make db-restart manage it. The worker and reconciliation command also need a Redis server reachable at the REDIS_URL in .env. The Compose Redis service does not publish a host port, so make redis-up alone cannot serve those host-run processes. This path uses host ports 3000, 8000, 8001, and 8002, so don't run it alongside ./run.sh's containers.

Two gotchas specific to this path:

• DB_CONNECTION_URL must be correct in .env. These targets read it directly; the config has no default and doesn't assemble one from the POSTGRES_* values. ./run.sh doesn't care, because compose overrides it to the in-network db hostname.
• Set LITELLM_BASE_URL=http://127.0.0.1:7070. It's blank in .env.spec, and unlike the Docker path nothing here fills it in. create_agent silently skips minting a LiteLLM key when it's empty (agent service, no error either way), so the agent is created and looks fine but can never answer.

Starting agents still needs a k3d cluster with loaded images, even natively. Bring one up with bash docker/k3d/k3d-up.sh and bash docker/k3d/k3d-load-images.sh, then point the host API at it:

export KUBECONFIG="$PWD/.k3d/kubeconfig-host.yaml"
export K8S_KUBECONFIG_PATH="$PWD/.k3d/kubeconfig-host.yaml"

Local Kubernetes (k3d)

Agents run as Kubernetes resources, so ./run.sh brings up a cluster automatically. We use k3d (k3s in Docker) from a helper container, so no host k3d or helm install is needed — only Docker and kubectl. The Kubernetes integration job provisions its own k3d cluster with AbsaOSS/k3d-action.

./run.sh drives docker/k3d/k3d-up.sh (cluster + LiteLLM) and docker/k3d/k3d-load-images.sh (agent base images). Both are idempotent and safe to run directly.

[!IMPORTANT] Keep the OPENCLAW_IMAGE / HERMES_IMAGE tags in sync with openclaw-base/VERSION and hermes-base/VERSION. CI publishes each base image under exactly its VERSION tag and the API launches pods from these env-var refs, so a mismatched tag runs an image that isn't the version the code expects. k3d-load-images.sh refuses to run otherwise, and skips the build for a tag it can already see in the cluster.

kubectl run ingest-check --rm -it --restart=Never --image=curlimages/curl -- \
  curl -sS -o /dev/null -w '%{http_code}\n' \
  http://host.docker.internal:8001/ingest/v1/openapi.json

Windows

The k3d flow needs bash — run.sh/stop.sh and the underlying docker/k3d/*.sh scripts are shell scripts. Two practical options:

• WSL2 (recommended) — enable Docker Desktop integration for the distro, then run ./run.sh inside WSL2.
• bash on PATH — e.g. Git Bash or MSYS2; run ./run.sh from that shell.

Requires Docker Desktop in Linux-container mode (the default).

Database migrations

./run.sh applies pending migrations after the database is ready and before starting the application services. Migration authoring, review, and verification commands live in the operations guidelines.

Tests and checks

The authoritative command list, prerequisites, and change-to-check matrix live in the testing guidelines.

Troubleshooting

Symptoms you're likely to hit once, with the actual cause.

docker exec aai_api ls -l "$(grep '^API_K8S_KUBECONFIG_PATH=' .env | cut -d= -f2-)"

docker exec k3d-${K3D_CLUSTER:-agentfarm-dev}-server-0 crictl images | grep -E 'openclaw|hermes'
grep -E '^(OPENCLAW|HERMES)_IMAGE=' .env

APT_MIRROR=mirror.csclub.uwaterloo.ca bash docker/k3d/k3d-load-images.sh

Deploying to Kubernetes

Requires a cluster with an ingress controller, a cert-manager ClusterIssuer, a StorageClass, and an OpenRouter API key. On your machine: kubectl, Helm 3, Helmfile 0.171.0 (the CI-pinned version), and the helm-diff plugin.

cp .env.deploy.spec .env.deploy
# replace every example image tag; fill in registry, passwords, hosts, and keys

./deploy.sh         # kubectl apply of the deploy RBAC, then helmfile sync

Helmfile brings up PostgreSQL (one instance each for the app, LiteLLM, and Firecrawl), Redis, the LiteLLM proxy, Firecrawl, the API with its worker and communications gateway, the UI, and a namespace-scoped Prometheus and Grafana. Ordering, values, and secrets live in helmfile.yaml.gotmpl; the charts are in helm/. Every option in .env.deploy.spec is commented.

AAI Labs runs two deploy paths of its own on top of the same charts: deploy.yml ships every staging/main push to the k3s testing-ground cluster, and deploy-public.yml deploys a vX.Y.Z tag to the hosted public Talos cluster. It pushes API/UI images under that release tag and runtime images under their independent VERSION tags to registry.agentbarn.dev. A manual dispatch of deploy-public.yml takes an existing release tag, and its skip_build input reuses the explicitly tagged images already in the registry.

Background: docs/architecture/runtime-and-deployment.md and docs/guidelines/operations.md.

Connecting agent email (manual step)

Agents reachable by email receive mail through a Cloudflare Email Worker. CI deploys the Worker, but it cannot connect the routing rule — Email Routing rules are Cloudflare dashboard state with no Terraform or API step in this repository, so mail bounces until someone points the rule at the Worker by hand. Do this once per environment, in this order:

1. Merge to staging/main. The deploy-worker job publishes agentbarn-email-inbound-<environment>. The Worker must exist first — the routing rule's destination picker only lists deployed Workers.
2. In Cloudflare, go to Email → Email Routing → Routing rules and point the custom address agent@<AGENT_EMAIL_DOMAIN> at that Worker. One rule serves every agent, provided subaddressing is enabled under Email Routing → Settings — it is off by default, and while it is off every agent address bounces 550 5.1.1 with nothing in the activity log.
3. Only now delete any Worker you deployed with wrangler --env local. Deleting it while a rule still points at it bounces all inbound mail for that environment.

Full setup — the two separate Cloudflare onboardings, the environment variables and secrets, quota limits, and secret rotation — is in docs/guidelines/operations.md.

Repository layout

Two dependencies live outside it: the Hermes and OpenClaw runtimes are upstream projects, and aai-cli, the tool the bundled skills drive, is built from a separate public AAI Labs repository at base-image build time. You can run and deploy the published base images without rebuilding them. The current local builder requires a GitHub token only to authenticate that public clone; it does not require private-source permission. Third-party components keep their own licences.

Getting help and contributing

Support, issue, discussion, and pull-request routes are collected in CONTRIBUTING.md. Report vulnerabilities privately by following SECURITY.md.

Licence

Apache 2.0. See LICENSE.

Built by AAI Labs in Vilnius, Lithuania.