Run Agent Barn locally

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

The GitHub repository uses the current agent-barn name. The local Kubernetes namespaces intentionally retain the historical agent-farm naming.

Copy the tracked environment template:

cp .env.spec .env

Open .env in your editor. The file documents every available setting.

Replace the placeholder values in the following groups.

Database and application

POSTGRES_USER=agentbarn
POSTGRES_PASSWORD=<local-database-password>
POSTGRES_DB=agentbarn
POSTGRES_PORT=5432

API_PORT=8000
ENVIRONMENT=local
UI_APP_URL=http://localhost:3000

SECRET_SIGNING_KEY=<random-signing-key>
PLATFORM_ADMIN_CREDENTIALS=[email protected]:<secure-password>

The Platform Administrator password must contain:

• At least eight characters
• An uppercase letter
• A lowercase letter
• A digit

Generate a random signing key with:

openssl rand -hex 32

Do not use the generated signing key as the Platform Administrator password.

Credential encryption

Set a Fernet key for encrypting Agent credentials:

AGENT_TOKEN_ENCRYPTION_KEY=<fernet-key>

One way to generate a Fernet key in a Python environment with cryptography installed is:

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

Keep this key stable. Changing it later prevents Agent Barn from decrypting credentials stored under the previous key.

Model routing

OPENROUTER_API_KEY=<openrouter-api-key>
LITELLM_MASTER_KEY=<stable-litellm-master-key>

Generate a local LiteLLM master key with:

printf 'sk-%s\n' "$(openssl rand -hex 16)"

Set the generated value once and keep it stable. LiteLLM uses it to protect the virtual keys it stores. Changing it between runs breaks Agents created with keys protected by the previous value.

Agent runtime images

Read the versions pinned by the repository:

printf 'OpenClaw: '
cat openclaw-base/VERSION

printf 'Hermes: '
cat hermes-base/VERSION

Set both image references using those exact tags:

OPENCLAW_IMAGE=agentbarn-openclaw-base:<openclaw-version>
HERMES_IMAGE=agentbarn-hermes-base:<hermes-version>
GH_TOKEN=<github-personal-access-token>

The image tag must match the corresponding VERSION file. Startup stops with a clear error when the values do not match.

Start the complete environment in detached mode:

./run.sh --detach

Alternatively, run the following command to follow application logs after startup:

./run.sh

Pressing Ctrl+C stops following the logs but leaves the stack running.

The startup script:

1. Validates Docker and the required environment values.
2. Starts LiteLLM and its PostgreSQL database.
3. Creates or resumes the local k3d cluster.
4. Writes host and container kubeconfig files under .k3d/.
5. Creates the agent-farm namespace and LiteLLM Secret.
6. Builds and imports the pinned Hermes and OpenClaw images.
7. Starts PostgreSQL and Redis.
8. Applies database migrations.
9. Builds and starts the Product API, Ingest API, worker, and web app.
10. Configures the API container to reach the local Kubernetes cluster.

Check the containers

docker compose -f compose.yml ps

Expected: The database, Redis, Product API, worker, web app, LiteLLM, and LiteLLM database are running.

Check the Product API

curl -fsS http://localhost:8000/api/v1/health

Expected response:

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

This confirms that the Product API can reach PostgreSQL.

Check the Ingest API

curl -sS -o /dev/null -w '%{http_code}\n' \
  http://localhost:8001/ingest/v1/openapi.json

Expected result:

200

The Ingest API stores Agent conversations and Tool Call activity. An Agent can run without visible activity when this path is unavailable, so verify it before troubleshooting the Activity UI.

Check the Kubernetes cluster

kubectl \
  --kubeconfig .k3d/kubeconfig-host.yaml \
  get namespace agent-farm

Expected: The agent-farm namespace is present.

Inspect all local Kubernetes workloads:

kubectl \
  --kubeconfig .k3d/kubeconfig-host.yaml \
  get pods -A

Open:

Sign in with the email and password from PLATFORM_ADMIN_CREDENTIALS in .env.