Skip to content
Back to search

agent-barn

run a fleet of AI agents on your own Kubernetes

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/aai-labs/agent-barn with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/aai-labs/agent-barn'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aai-labs--agent-barn/badge.svg)](/listings/aai-labs--agent-barn)

HTML

<a href="/listings/aai-labs--agent-barn"><img src="/api/listings/aai-labs--agent-barn/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://agentbarn.dev/guides/get-started/local-quickstart).

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](#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](#development)).

**Required credentials**

1. An **[OpenRouter](https://openrouter.ai) API key** — every agent's model calls route through it.

**Local ports** — these must be free:

| Port | Service | | ------- | -------------------------- | | `3000` | UI | | `5432` | PostgreSQL | | `7070` | LiteLLM proxy | | `8000` | API | | `8001` | Ingest (runtime telemetry) | | `8002` | Communications gateway | | `16443` | k3d Kubernetes API |

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:

| Variable | What to put in it | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | local credentials and a database name; the database is created on first run | | `POSTGRES_PORT` | a free host port; keep the default `5432` when available | | `SECRET_SIGNING_KEY` | any random string | | `PLATFORM_ADMIN_CREDENTIALS` | `email:password` for the admin account created at startup — the password needs 8+ characters, upper, lower, and a digit | | `ENVIRONMENT`, `WEB_APP_URL`, `API_PORT` | leave the `.env.spec` defaults | | `AGENT_TOKEN_ENCRYPTION_KEY` | a Fernet key — generate it below | | `OPENROUTER_API_KEY` | your OpenRouter key; passed to LiteLLM and used for the model picker | | `LITELLM_MASTER_KEY` | a **stable** admin key — generate it below | | `AGENT_LITELLM_BASE_URL` | `http://host.docker.internal:7070` so agent pods can reach LiteLLM through the host | | `OPENCLAW_IMAGE`, `HERMES_IMAGE` | full `name:tag`; each tag must equal the matching `openclaw-base/VERSION` / `hermes-base/VERSION` |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 873 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src=".github/assets/agent-barn-logo.webp" alt="Agent Barn" width="96">
  3. # Agent Barn
  4. **AI coworkers in Slack, Microsoft Teams, Telegram, and Discord, running on your infrastructure.**
  5. [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
  6. [![Discord](https://img.shields.io/badge/discord-join-5865F2)](https://discord.gg/A3vJF5ZKnu)
  7. [Website](https://agentbarn.dev) · [Docs](https://agentbarn.dev/guides) · [Recipes](https://agentbarn.dev/recipes) · [Discord](https://discord.gg/A3vJF5ZKnu)
  8. </div>
  9. ---
  10. Agent Barn is an open-source control plane for AI agents. Define an agent once,
  11. connect it to the tools your team already uses, and run it in your own
  12. Kubernetes cluster. No seat licence, no second workspace to check.
  13. - **Talk to your tools.** Agents live in Slack, Microsoft Teams, Telegram, and Discord.
  14. - **A model per agent.** Each gets its own virtual key on a LiteLLM proxy in your namespace.
  15. - **See what it costs.** Per-agent token and spend attribution, not one opaque monthly number.
  16. - **Multi-tenant from the start.** Organisation roles and per-agent access roles, isolated in the data layer.
  17. - **Audit what happened.** Conversation history, a tool-call log, and a domain-event trail.
  18. - **Self-host it.** Helm charts, Helmfile, PostgreSQL, your cluster.
  19. Everything runs in your namespace: the control plane, the database, the model
  20. proxy, and one pod per running agent. Outbound traffic goes to OpenRouter through
  21. the LiteLLM proxy you operate, to whichever tool APIs you connect, and, for installs
  22. that keep it on, to Agent Barn's product analytics
  23. ([usage analytics](#usage-analytics)).
  24. Credentials are encrypted at rest in your own PostgreSQL.
  25. ## Contents
  26. - [Quick start](#quick-start) — [before you begin](#before-you-begin), then six steps to a running agent
  27. - [What ships in the box](#what-ships-in-the-box) — [agents](#agents), [skills](#skills), [runtimes](#runtimes)
  28. - [Capabilities](#capabilities)
  29. - [Development](#development) — [native](#native-non-docker-development), [k3d](#local-kubernetes-k3d), [migrations](#database-migrations), [tests](#tests-and-checks), [troubleshooting](#troubleshooting)
  30. - [Deploying to Kubernetes](#deploying-to-kubernetes) — [usage analytics](#usage-analytics), [connecting agent email](#connecting-agent-email-manual-step), [connecting OneDrive](#connecting-onedrive-manual-step)
  31. - [Repository layout](#repository-layout)
  32. - [Getting help and contributing](#getting-help-and-contributing)
  33. ## Quick start
  34. Start the full local stack — control plane, database, model proxy, and the
  35. Kubernetes cluster agents run on — and hire your first agent. The step-by-step
  36. version with screenshots is at
  37. [agentbarn.dev/guides/get-started](https://agentbarn.dev/guides/get-started/local-quickstart).
  38. ### Before you begin
  39. **Required software**
  40. - **Git** — used to clone the repository.
  41. - **Docker with Compose v2.24 or later** — everything runs in containers, including the local Kubernetes cluster.
  42. - **`bash`** — `run.sh` and `stop.sh` are shell scripts. On Windows, see [Windows](#windows).
  43. - **`kubectl`** — used to seed the cluster namespace and secret.
  44. - **[uv](https://docs.astral.sh/uv/)** — runs the host-side Garage bootstrap with Python 3.14; uv can download the managed interpreter.
  45. - **OpenSSL** — used below to generate local keys.
  46. - **curl** — used by the verification steps.
  47. Containerized startup still needs uv/Python for storage bootstrap; installing uv
  48. lets it supply the managed Python interpreter. Node.js and pnpm are needed only
  49. for native UI development, tests and lint (see [Development](#development)).
  50. **Required credentials**
  51. 1. An **[OpenRouter](https://openrouter.ai) API key** — every agent's model calls route through it.
  52. **Local ports** — these must be free:
  53. | Port | Service |
  54. | ------- | -------------------------- |
  55. | `3000` | UI |
  56. | `3900` | Garage S3 (loopback only; configurable) |
  57. | `5432` | PostgreSQL |
  58. | `7070` | LiteLLM proxy |
  59. | `8000` | API |
  60. | `8001` | Ingest (runtime telemetry) |
  61. | `8002` | Communications gateway |
  62. | `8003` | Agent Memory gateway |
  63. | `8004` | Credential gateway |
  64. | `16443` | k3d Kubernetes API |
  65. Make sure these ports are free before starting the full stack. The configurable
  66. ports are identified in `.env.spec` and the k3d helper scripts.
  67. ### 1. Clone the repository
  68. ```bash
  69. git clone https://github.com/aai-labs/agent-barn.git
  70. cd agent-barn
  71. ```
  72. ### 2. Create the local configuration
  73. ```bash
  74. cp .env.spec .env
  75. ```
  76. Now fill in these values. Every option in `.env.spec` is commented, and
  77. anything not listed here has a working local default:
  78. | Variable | What to put in it |
  79. | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
  80. | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | local credentials and a database name; the database is created on first run |
  81. | `POSTGRES_PORT` | a free host port; keep the default `5432` when available |
  82. | `SECRET_SIGNING_KEY` | any random string |
  83. | `PLATFORM_ADMIN_CREDENTIALS` | `email:password` for the admin account created at startup — the password needs 8+ characters, upper, lower, and a digit |
  84. | `ENVIRONMENT`, `WEB_APP_URL`, `API_PORT` | leave the `.env.spec` defaults |
  85. | `AGENT_TOKEN_ENCRYPTION_KEY` | a Fernet key — generate it below |
  86. | `OPENROUTER_API_KEY` | your OpenRouter key; passed to LiteLLM and used for the model picker |
  87. | `LITELLM_MASTER_KEY` | a **stable** admin key — generate it below |
  88. | `AGENT_LITELLM_BASE_URL` | `http://host.docker.internal:7070` so agent pods can reach LiteLLM through the host |
  89. | `OPENCLAW_IMAGE`, `HERMES_IMAGE` | full `name:tag`; each tag must equal the matching `openclaw-base/VERSION` / `hermes-base/VERSION` |
  90. Generate the two keys:
  91. ```bash
  92. # AGENT_TOKEN_ENCRYPTION_KEY — encrypts platform credentials at rest
  93. openssl rand -base64 32 | tr '+/' '-_'
  94. # LITELLM_MASTER_KEY
  95. echo "sk-$(openssl rand -hex 16)"
  96. ```
  97. > [!IMPORTANT]
  98. > `LITELLM_MASTER_KEY` must stay stable. LiteLLM encrypts the virtual keys it
  99. > stores with this value, so changing it later breaks every agent created under
  100. > the old one.
  101. You don't need to touch `API_K8S_KUBECONFIG_PATH` — `run.sh` sets it for you once
  102. the cluster is up.
  103. ### 3. Start Agent Barn
  104. ```bash
  105. ./run.sh
  106. ```
  107. This validates `.env`, bootstraps persistent private Garage storage, brings up
  108. the k3d cluster and LiteLLM, builds and loads the agent base images, starts `db`
  109. and `redis`, runs database migrations, then starts `api`, `worker`, `sync-engine`,
  110. `communications`, `memory`, `artifact-purge`, `workflow-maintenance`, and `ui` with hot reload and follows
  111. the logs. `Ctrl-C` detaches without stopping anything; use `./run.sh --detach`
  112. to skip the logs entirely.
  113. The memory gateway needs a running Hindsight backend to list or save memories.
  114. The optional `local-hindsight` Compose profile provides one; see
  115. [Agent Memory deployment](docs/guidelines/operations.md#agent-memory-deployment).
  116. If a startup value checked by `run.sh` is missing, the script fails immediately
  117. and lists it.
  118. > [!NOTE]
  119. > The **first** run builds both agent base images from scratch and takes a
  120. > while. Later runs skip any image tag already present in the cluster.
  121. ### 4. Verify the environment
  122. The API reports its own database connectivity:
  123. ```bash
  124. curl -s localhost:8000/api/v1/health
  125. # {"status":"ok","db":"connected"}
  126. ```
  127. Then check the UI answers and every container is healthy:
  128. ```bash
  129. curl -s -o /dev/null -w '%{http_code}\n' localhost:3000 # → 200
  130. docker compose ps # all Up / healthy
  131. ```
  132. Finally, confirm the cluster agents will run on is ready and its namespace was
  133. seeded:
  134. ```bash
  135. export KUBECONFIG=.k3d/kubeconfig-host.yaml
  136. kubectl get nodes # one Ready node
  137. kubectl get ns agent-farm # Active
  138. ```
  139. > [!NOTE]
  140. > The namespace is `agent-farm`, not `agent-barn`. Kubernetes namespaces were
  141. > deliberately left unrenamed in the rebrand — moving running workloads would
  142. > mean recreating every agent Deployment and PVC.
  143. ### 5. Sign in
  144. Open **`http://localhost:3000`** and log in with the `email:password` you set in
  145. `PLATFORM_ADMIN_CREDENTIALS`.
  146. > [!TIP]
  147. > If the API exited at startup with `500: Error while initializing startup data`,
  148. > that password almost certainly failed the policy check. See
  149. > [Troubleshooting](#troubleshooting).
  150. ### 6. Create an organisation, then hire an agent
  151. Agents are organisation-scoped and a fresh database has none, so **create an
  152. organisation first**. Then pick a template (see
  153. [Agents](#agents)), choose a model, attach any credentials its skills need, and
  154. start it. Connecting it to Slack, Teams, Telegram, or Discord is a per-agent
  155. Communication Connection; the UI walks through each platform's setup.
  156. ### Stopping and restarting
  157. | Command | What it does |
  158. | ------------------- | ----------------------------------------------------------------------- |
  159. | `./run.sh` | start everything and follow logs |
  160. | `./run.sh --detach` | same, without following logs |
  161. | `./stop.sh` | stop containers; DB/redis data and the k3d cluster survive |
  162. | `./stop.sh --clean` | also delete the k3d cluster (images reload next run); volumes untouched |
  163. | `make restart-ui` | refresh the running Docker UI after adding an App Router directory |
  164. `make run`, `make stop`, and `make stop-clean` are thin wrappers around the same
  165. scripts. Volumes are never deleted by either script.
  166. ## What ships in the box
  167. ### Agents
  168. An agent is a template plus a model, one or more communication connections, and
  169. a set of credentialed skills. These templates ship as seeds:
  170. | Agent | What it does |
  171. | ------------------- | ----------------------------------------------------------------------------------------------------- |
  172. | PR Reviewer | Reviews pull requests for correctness, clarity, and style |
  173. | Documentation Agent | Documents merged pull requests into Confluence, keeps a changelog, and posts a weekly digest to Slack |
  174. | Email Reminder | Monitors a mailbox, flags action-required mail, and posts P1/P2 pings to Slack |
  175. | Jira Task Helper | Turns a plain-language request, in any language, into a structured Jira task |
  176. | Scrum Master | Runs sprint ceremonies, tracks blockers, keeps the team on cadence |
  177. | General Purpose | One flexible assistant for ad-hoc work |
  178. Templates are content, not code: a `settings.yaml` plus Markdown artifacts
  179. (`soul`, `identity`, `user`, `tools`, `agents`, `boot`, `bootstrap`,
  180. `heartbeat`), with anything a template omits inherited from shared defaults.
  181. The seeds in
  182. [`api/domains/templates/predefined/seeds/`](api/domains/templates/predefined/seeds/)
  183. bootstrap the platform lineages once; after that, new versions are authored
  184. through the platform admin flow, and organisations fork or override them per
  185. agent. Details:
  186. [`docs/features/templates-and-skills.md`](docs/features/templates-and-skills.md).
  187. Each template has a guided setup at
  188. [agentbarn.dev/recipes](https://agentbarn.dev/recipes).
  189. ### Skills
  190. Skills are what agents can actually do:
  191. Apollo · Bitbucket · Confluence · Excel · GitHub · GitLab · Google Drive · HubSpot ·
  192. Jira · Merkys · OpenPanel · Pipedrive · PostHog · Zoho Mail
  193. Each mounts documentation into the agent's workspace and is gated on the
  194. credential its provider needs, so an agent only gets a skill once the matching
  195. credential is attached. Skills whose credential lifecycle isn't modelled yet
  196. (Excel, Google Drive, HubSpot, OpenPanel, PostHog) are attachable but not
  197. auto-attached — Excel needs no credential at all, since it works on local files.
  198. Agents also reach a self-hosted Firecrawl for web retrieval.
  199. Building one is a
  200. [contribution we'd welcome](CONTRIBUTING.md#contribute-a-template-or-bundled-skill).
  201. Open a Discussion first so we can tell you if one is already in progress.
  202. ### Runtimes
  203. Agents run as pods, one per agent, from a pinned base image:
  204. | Runtime | Base image | Notes |
  205. | -------- | ---------------------------------- | -------------------------------------------------- |
  206. | OpenClaw | [`openclaw-base/`](openclaw-base/) | Default runtime; command approval is always `AUTO` |
  207. | Hermes | [`hermes-base/`](hermes-base/) | Supports the per-agent command-approval mode |
  208. Both consume the same runtime-neutral communications protocol, so every platform
  209. works on either runtime. Both are upstream projects; this repository holds the
  210. Dockerfiles that pin and extend them, the telemetry plugins they load, and the
  211. builders that turn an agent record into Kubernetes resources.
  212. ## Capabilities
  213. | Area | What's there | Docs |
  214. | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
  215. | Agent artifacts | Private file publication from chat/workflows, short-lived app download links, per-Agent storage provisioning, infinite artifact lists and permission-gated deletion | [`features/agent-artifacts.md`](docs/features/agent-artifacts.md) |
  216. | Agent lifecycle | Start, stop, monitor; per-agent model within the organisation's default and allowlist; per-agent channel allowlist and DM policy | [`features/agents.md`](docs/features/agents.md) |
  217. | Communication | Slack, Microsoft Teams, Telegram, Discord. An agent may own several connections, including more than one on the same platform. Slack apps are created by hand from a generated manifest; Teams connections export an installable app package | [`features/communications/`](docs/features/communications/) |
  218. | Templates and skills | Versioned templates and skills, seeded on startup, forkable per organisation, with per-agent overrides; agents pin the skill version they run | [`features/templates-and-skills.md`](docs/features/templates-and-skills.md) |
  219. | Activity | Conversation history and a tool-call audit log per agent, pushed from the runtime to the ingest API | [`features/activity-and-ingest.md`](docs/features/activity-and-ingest.md) |
  220. | Costs | Per-agent and per-organisation token and spend attribution | [`features/costs.md`](docs/features/costs.md) |
  221. | Identity and access | Sign-up and sign-in with Google into a trial organization, login, logout, access + refresh tokens in an httpOnly cookie, password change and reset; organisations with fixed permission-backed roles, plus separate per-agent access roles and assignments | [`features/identity-and-organizations.md`](docs/features/identity-and-organizations.md) |
  222. | Platform administration | User and organisation management, platform statistics, and the Event Delivery Monitor | [`features/platform-administration/`](docs/features/platform-administration/) |
  223. | Integrations | Per-agent provider credentials, organisation-scoped shared credentials, Google OAuth for Google Workspace (Gmail, Calendar, Drive, Sheets), and Custom API connections to any public HTTPS API (API key, Bearer, Basic or OAuth2 client credentials) | [`features/integrations.md`](docs/features/integrations.md) |
  224. | Domain events | Transactional outbox, a Dramatiq worker, event handlers, and a security-audit projection | [`features/domain-events.md`](docs/features/domain-events.md) |
  225. | Runtime and deployment | Kubernetes agent resources, Helm + Helmfile, namespace-scoped Prometheus and Grafana | [`architecture/runtime-and-deployment.md`](docs/architecture/runtime-and-deployment.md) |
  226. ## Development
  227. `./run.sh` is enough for most work. For faster iteration, or to run only part of
  228. the stack, use the native path below. The contribution workflow and engineering
  229. context routes start in [CONTRIBUTING.md](CONTRIBUTING.md).
  230. Native development, tests, and lint additionally need Make, Python `3.14` +
  231. [uv](https://github.com/astral-sh/uv) and Node.js `24` +
  232. [pnpm `11.17.0`](https://pnpm.io/), matching the repository and CI pins.
  233. ### Native (non-Docker) development
  234. Each `dev-*` service target watches its own source. Run the ones you need in
  235. separate terminals, alongside `make db-up`:
  236. ```bash
  237. make setup # uv sync + pnpm install; creates .env from .env.spec if absent
  238. make db-up # Postgres only
  239. make migrate # apply migrations
  240. make dev-api # API :8000, Ingest :8001, Communications :8002, Memory :8003, Credentials :8004
  241. make dev-ui # UI on :3000, hot reload
  242. make dev-worker # Dramatiq worker, hot reload
  243. make dev-sync-engine # Sync Engine: Agent file sync, one pass every 30 s
  244. make dev-ingest # Ingest only (normally started by dev-api)
  245. make dev-communications # Communications only (normally started by dev-api)
  246. make dev-gateway # Credential gateway only (normally started by dev-api)
  247. make dev-memory # Memory gateway only (normally started by dev-api)
  248. make reconcile # one-shot repair pass for stuck/unpublished deliveries
  249. ```
  250. The db/redis targets and `./stop.sh` work before Garage has been configured.
  251. For native file uploads/downloads, run `make garage-up` before `make dev-api`;
  252. this generates private API management settings and a loopback endpoint as well.
  253. Agent creation queues storage without waiting; Artifacts shows progress and lets
  254. existing Agents provision or retry. No separate provisioner service is needed. See [Garage operations](docs/guidelines/garage.md). The full `./run.sh` path starts
  255. Garage and the purge worker automatically, without a profile.
  256. `make db-down` stops PostgreSQL; `make db-logs` and `make db-restart` manage it.
  257. The worker and reconciliation command also need a Redis server reachable at the
  258. `REDIS_URL` in `.env`. The Compose Redis service does not publish a host port,
  259. so `make redis-up` alone cannot serve those host-run processes. This path uses
  260. host ports `3000`, `8000`, `8001`, `8002`, `8003`, and `8004`, so don't run it alongside
  261. `./run.sh`'s containers.
  262. Two gotchas specific to this path:
  263. - **`DB_CONNECTION_URL` must be correct in `.env`.** These targets read it
  264. directly; the config has no default and doesn't assemble one from the
  265. `POSTGRES_*` values. `./run.sh` doesn't care, because compose overrides it to
  266. the in-network `db` hostname.
  267. - **Set `LITELLM_BASE_URL=http://127.0.0.1:7070`.** It's blank in `.env.spec`,
  268. and unlike the Docker path nothing here fills it in. `create_agent` silently
  269. skips minting a LiteLLM key when it's empty
  270. ([agent service](api/domains/agents/service.py), no error either way),
  271. so the agent is created and _looks_ fine but can never answer.
  272. Starting agents still needs a k3d cluster with loaded images, even natively.
  273. Bring one up with `bash docker/k3d/k3d-up.sh` and
  274. `bash docker/k3d/k3d-load-images.sh`, then point the host API at it:
  275. ```bash
  276. export KUBECONFIG="$PWD/.k3d/kubeconfig-host.yaml"
  277. export K8S_KUBECONFIG_PATH="$PWD/.k3d/kubeconfig-host.yaml"
  278. ```
  279. ### Agent artifacts in development
  280. Local artifacts use a private, single-node Garage container and persistent Docker
  281. volumes. **No AWS account, S3 credentials, GitHub Secrets, or manual Kubernetes
  282. bootstrap is needed locally.** Docker Compose 2.24+ and uv are required. The first
  283. startup generates local credentials in the ignored `.garage/` directory; later
  284. starts reuse them and the existing volumes.
  285. For the full-stack path, complete the `.env` setup above and start the stack:
  286. ```bash
  287. ./run.sh --detach
  288. ```
  289. The launcher prepares Garage, applies the artifact migrations, and starts background
  290. maintenance automatically. After signing in, check storage with:
  291. ```bash
  292. make garage-status
  293. # The application services and Garage should be running:
  294. docker compose ps garage api artifact-purge ui
  295. ```
  296. Open an Agent's **Artifacts** tab. A new Agent queues private storage setup without
  297. waiting for Garage; the tab shows progress. On an existing Agent, click **Provision**
  298. if storage has not been prepared. Provisioning, retry and deletion require
  299. `agent.update`; users with current `agent.read` access can view and download.
  300. Start the Agent, or update/restart an Agent created before this feature so it gets
  301. the runtime file tool. Ask it to create a small CSV and provide the download link.
  302. The artifact should appear in **Artifacts**; downloading it requests a fresh link.
  303. The trash action opens a confirmation dialog, and files pinned by active runs or
  304. reviews remain protected. This is a developer smoke test; external messaging and
  305. model/tool selection still depend on the configured runtime and provider.
  306. For the native API/UI path, complete the native database/migration setup above,
  307. then prepare storage **before** starting the API:
  308. ```bash
  309. make garage-up # persistent storage + ignored API/native management settings
  310. make garage-status
  311. make dev-api # terminal 1; loads generated storage settings
  312. # In terminal 2:
  313. make dev-ui
  314. # Recover pending requests / run one bounded cleanup pass when needed:
  315. make purge-artifacts
  316. ```
  317. For an Agent running in k3d, `ARTIFACT_RUNTIME_BASE_URL` in `.env` must point to
  318. the native API address reachable from Agent containers. The default uses
  319. `host.docker.internal:8000`; if `API_DEV_PORT` differs, update that URL and restart
  320. the API and the Agent. The browser-facing download origin is `WEB_APP_URL`.
  321. Native post-response provisioning runs immediately, but unattended retry needs the
  322. maintenance worker; `make purge-artifacts` provides an explicit one-shot recovery
  323. pass. Restart the native API after re-running storage bootstrap. Garage management
  324. and per-Agent data credentials stay server-side. Generated private files live in
  325. ignored `.garage/`; keep that directory and the named data volumes intact. Backup,
  326. restore and cluster installation are documented in [Garage operations](docs/guidelines/garage.md).
  327. | Symptom | What to check |
  328. | --- | --- |
  329. | Storage unavailable / not configured | Confirm Docker is running, run `make garage-up`, then restart the API so it loads generated settings. Check `make garage-status`. |
  330. | Garage cannot start on port 3900 | Set `GARAGE_S3_PORT` in `.env` before the first `make garage-up`. Existing initialized stores keep their saved port; follow the operations guide to migrate or restore. |
  331. | Provisioning failed or stays pending | Check `docker compose logs --tail=100 api artifact-purge garage`; in native development run `make purge-artifacts` and retry from Artifacts. |
  332. | Download links use the wrong host/port | `WEB_APP_URL` must match the UI origin that download clients can reach. Adjust it for a second worktree and restart the API. |
  333. | A file uses the previous storage layout | This PR deliberately does not migrate old shared-bucket files. Re-upload or plan a verified migration; provisioning a new bucket does not move old bytes. |
  334. | Delete reports an active pin | The owning run or review must release its reference through its lifecycle before deletion. |
  335. Artifact checks use disposable PostgreSQL/Garage and never need installation
  336. storage credentials:
  337. ```bash
  338. make check-api check-ui lint-ui check-migrations
  339. (cd api && uv run pytest tests/integration/test_artifacts.py tests/integration/test_artifact_review.py tests/integration/test_artifact_creation.py -q)
  340. (cd ui && pnpm exec playwright install chromium)
  341. (cd ui && pnpm exec playwright test tests/e2e/artifacts.spec.ts)
  342. ```
  343. Helm chart checks and the opt-in real-image/storage/browser contracts have extra
  344. prerequisites. See [artifact test guidance](docs/guidelines/testing.md#agent-artifact-storage-and-runtime-contracts),
  345. [configuration and lifecycle](docs/features/agent-artifacts.md), and
  346. [verification evidence](docs/features/agent-artifacts/EVIDENCE.md) for exact limits,
  347. rollback, test boundaries and recorded results.
  348. ### Local Kubernetes (k3d)
  349. Agents run as Kubernetes resources, so `./run.sh` brings up a cluster
  350. automatically. We use [k3d](https://k3d.io) (k3s in Docker) from a helper
  351. container, so no host `k3d` or `helm` install is needed — only Docker and
  352. `kubectl` (the optional [local Prometheus](#resource-usage-local-prometheus) also
  353. needs `helm`). The Kubernetes integration job provisions its own k3d cluster with
  354. [`AbsaOSS/k3d-action`](https://github.com/AbsaOSS/k3d-action).
  355. `./run.sh` drives `docker/k3d/k3d-up.sh` (cluster + LiteLLM) and
  356. `docker/k3d/k3d-load-images.sh` (agent base images). Both are idempotent and
  357. safe to run directly.
  358. > [!IMPORTANT]
  359. > Keep the `OPENCLAW_IMAGE` / `HERMES_IMAGE` tags in sync with
  360. > `openclaw-base/VERSION` and `hermes-base/VERSION`. CI publishes each base image
  361. > under exactly its `VERSION` tag and the API launches pods from these env-var
  362. > refs, so a mismatched tag runs an image that isn't the version the code
  363. > expects. `k3d-load-images.sh` refuses to run otherwise, and skips the build for
  364. > a tag it can already see in the cluster.
  365. <details>
  366. <summary><b>The two kubeconfigs, and how pods reach the host</b></summary>
  367. `./run.sh` writes two kubeconfigs into `.k3d/` (gitignored) — the same cluster,
  368. reached differently depending on where the client runs:
  369. - `.k3d/kubeconfig-host.yaml` — server on `127.0.0.1`, for host tools
  370. (`kubectl`, `helm`, `make dev-api`).
  371. - `.k3d/kubeconfig-internal.yaml` — server on `host.docker.internal`, for the
  372. API running **inside** Docker (`run.sh` points `API_K8S_KUBECONFIG_PATH` here
  373. automatically).
  374. Agent pods inside k3d reach LiteLLM at `http://host.docker.internal:7070`, so
  375. `AGENT_LITELLM_BASE_URL` must use that address (and the selected LiteLLM port).
  376. On
  377. Docker Desktop that name resolves inside pods automatically; on a native Linux
  378. docker engine, `k3d-up.sh` adds a CoreDNS entry (via the `coredns-custom` config
  379. map) mapping it to the cluster network gateway. No manual setup on either
  380. platform.
  381. </details>
  382. <details>
  383. <summary><b>Runtime telemetry — where conversations and tool calls come from</b></summary>
  384. Agents don't store their history in the pod. Runtime plugins push events to the
  385. ingest API and the UI reads what was persisted, so a broken path means agents run
  386. but their activity stays empty.
  387. Ingest listens on `8001`, separate from the main API on `8000`, and pods reach it
  388. through the host via `host.docker.internal`, same as LiteLLM.
  389. `INGEST_BASE_URL=http://host.docker.internal:8001/ingest/v1` is the default for
  390. both `run.sh` and `make dev-api`, overriding the in-cluster Service address that
  391. only applies when the API itself runs in k8s. Override `INGEST_BASE_URL` (or
  392. `INGEST_PORT`) for a different address.
  393. To check the hop from inside the cluster:
  394. ```bash
  395. kubectl run ingest-check --rm -it --restart=Never --image=curlimages/curl -- \
  396. curl -sS -o /dev/null -w '%{http_code}\n' \
  397. http://host.docker.internal:8001/ingest/v1/openapi.json
  398. ```
  399. `200` means it works; the event endpoint behind it authenticates each pod with
  400. its own `INGEST_API_KEY`. A connection error means the hop is broken — in native
  401. mode check `make dev-ingest` is running, and on native Linux check the host
  402. firewall allows the k3d bridge network to reach port 8001.
  403. </details>
  404. <details>
  405. <summary><b>Communication connections</b></summary>
  406. Slack, Microsoft Teams, Telegram, and Discord sessions run in each Agent's native
  407. Hermes or OpenClaw runtime. Web Chat and Email use the separately served
  408. Communications gateway on port `8002`. For those gateway-owned Connections, Agent
  409. pods claim and complete deliveries through
  410. `http://host.docker.internal:8002/communications/v1`, because the Compose service
  411. name isn't resolvable from k3d. `./run.sh` and `make dev-api` start the gateway
  412. automatically. Override `COMMUNICATIONS_PORT` when the host port is already in use.
  413. See the [transport contract](docs/architecture/runtime-and-deployment.md#platform-plugin-boundary)
  414. and [rollout runbook](docs/guidelines/operations.md#native-runtime-gateway-rollout).
  415. </details>
  416. <details>
  417. <summary><b>Parallel worktrees</b></summary>
  418. The k3d and LiteLLM helpers expose environment-variable overrides for their
  419. names and ports, but the full Compose application still uses shared container
  420. names, volumes, and ports. Two complete `./run.sh` stacks therefore cannot run
  421. side by side. Share one full stack, or run only the required native services
  422. against separately named dependencies.
  423. </details>
  424. #### Resource usage (local Prometheus)
  425. The Resource usage tab and the Agents overview read each Agent's CPU and memory
  426. from Prometheus. Compose has none, so until you install one those views say
  427. resource usage is not configured; status and cost are unaffected.
  428. To see real numbers locally, install the monitoring chart into the k3d cluster. This
  429. is the one step that needs `helm` and `kubectl` on the host:
  430. ```bash
  431. make dev-monitoring
  432. ```
  433. Keep the port-forward running in its own terminal. The API in Docker reaches
  434. Prometheus through it:
  435. ```bash
  436. make forward-prometheus
  437. ```
  438. Recreate the API container so it picks up the new `PROMETHEUS_PASSWORD`:
  439. ```bash
  440. docker compose up -d api
  441. ```
  442. Then stop and start an Agent. The script that reports usage ships with the Agent's
  443. configuration, so a running Agent reports only after a restart.
  444. `make dev-monitoring` installs the same `helm/monitoring` chart a deploy uses, with
  445. the LiteLLM metrics-key hook skipped because LiteLLM runs in Compose. It writes a
  446. `PROMETHEUS_PASSWORD` to `.env` if there is none, creates the `agent-farm-user`
  447. ServiceAccount Prometheus runs as, and is safe to run again. Set `PROMETHEUS_PORT` to
  448. change the host port (default `9090`). Running the API natively (`make dev-api`)? Add
  449. `PROMETHEUS_URL=http://localhost:9090` to `.env`. To remove it:
  450. `helm uninstall monitoring -n agent-farm`.
  451. ### Windows
  452. The k3d flow needs **`bash`** — `run.sh`/`stop.sh` and the underlying
  453. `docker/k3d/*.sh` scripts are shell scripts. Two practical options:
  454. - **WSL2 (recommended)** — enable Docker Desktop integration for the distro,
  455. then run `./run.sh` inside WSL2.
  456. - **`bash` on `PATH`** — e.g. Git Bash or MSYS2; run `./run.sh` from that shell.
  457. Requires Docker Desktop in Linux-container mode (the default).
  458. ### Database migrations
  459. `./run.sh` applies pending migrations after the database is ready and before
  460. starting the application services. Migration authoring, review, and verification
  461. commands live in the
  462. [operations guidelines](docs/guidelines/operations.md#database-migrations).
  463. ### Tests and checks
  464. The authoritative command list, prerequisites, and change-to-check matrix live
  465. in the [testing guidelines](docs/guidelines/testing.md).
  466. ### Troubleshooting
  467. Symptoms you're likely to hit once, with the actual cause.
  468. <details>
  469. <summary><b>API exits at startup with <code>500: Error while initializing startup data</code></b></summary>
  470. Scroll up in the log for the real error. The usual cause is the password in
  471. `PLATFORM_ADMIN_CREDENTIALS` failing the API's own policy (≥8 characters, upper,
  472. lower, digit) while bootstrapping the platform admin.
  473. </details>
  474. <details>
  475. <summary><b>Containerized API can't reach the cluster: <code>x509: certificate is valid for 127.0.0.1, ... not host.docker.internal</code></b></summary>
  476. `kubeconfig-internal.yaml` dials the API server by that hostname and verifies the
  477. certificate, so the name has to be in the cert's SAN list. A cluster **created
  478. before this was fixed** may carry the old certificate — `./stop.sh --clean` then
  479. `./run.sh` reissues it. Host mode (`make dev-api`) is immune because it connects
  480. to `127.0.0.1`.
  481. </details>
  482. <details>
  483. <summary><b>Starting an agent fails with <code>Invalid kube-config file. No configuration found.</code></b></summary>
  484. The configured kubeconfig path doesn't resolve to a real file — either
  485. `API_K8S_KUBECONFIG_PATH`/`K8S_KUBECONFIG_PATH` is unset, or it's a relative path
  486. resolved against the wrong working directory. `run.sh` sets
  487. `API_K8S_KUBECONFIG_PATH` for you; in native mode `K8S_KUBECONFIG_PATH` must be
  488. relative to `api/` (the directory `make dev-api` runs from) or absolute. Verify
  489. inside the container:
  490. ```bash
  491. docker exec aai_api ls -l "$(grep '^API_K8S_KUBECONFIG_PATH=' .env | cut -d= -f2-)"
  492. ```
  493. It must be `/app/.k3d/kubeconfig-internal.yaml` — `compose.yml` mounts `./.k3d`
  494. read-only at `/app/.k3d`.
  495. </details>
  496. <details>
  497. <summary><b>Agent pod stuck in <code>ErrImagePull</code> / <code>ImagePullBackOff</code></b></summary>
  498. The base image for that tag isn't in _that_ cluster. Pods run
  499. `imagePullPolicy=IfNotPresent` against a private registry, so an image that was
  500. never imported cannot be pulled. Compare what's in the cluster against what the
  501. API asks for:
  502. ```bash
  503. docker exec k3d-${K3D_CLUSTER:-agentfarm-dev}-server-0 crictl images | grep -E 'openclaw|hermes'
  504. grep -E '^(OPENCLAW|HERMES)_IMAGE=' .env
  505. ```
  506. Fix by running `./run.sh` again (it reloads any image missing from the cluster),
  507. or `bash docker/k3d/k3d-load-images.sh` directly with the same `K3D_CLUSTER`.
  508. A second, less obvious cause: an image that _was_ imported can still disappear
  509. later. Imported images are unreferenced whenever no agent is running one, and
  510. kubelet garbage-collects unreferenced images under disk pressure (seen at
  511. `usage=87 highThreshold=85` on a constrained host). With
  512. `imagePullPolicy=IfNotPresent` against a private registry and no pull secret
  513. seeded locally, a GC'd image can't be re-pulled — only reimported.
  514. `docker system df` / `docker stats --no-stream` will show whether disk pressure
  515. is the actual trigger before you re-run the fix above.
  516. </details>
  517. <details>
  518. <summary><b>Warning <code>FailedToRetrieveImagePullSecret (registry-pull-secret)</code> repeating on a pod</b></summary>
  519. Expected locally and harmless on its own — the local flow imports images instead
  520. of pulling, and nothing seeds that secret. It becomes the real error only when
  521. the image is genuinely absent, in which case you'll also see `ErrImagePull`
  522. above.
  523. </details>
  524. <details>
  525. <summary><b>Agent pod <code>CrashLoopBackOff</code> with <code>OOMKilled</code> / exit code 137</b></summary>
  526. Hermes and OpenClaw pods request `320Mi` and have a `1Gi` memory limit. Inspect
  527. the pod with `kubectl -n agent-farm describe pod POD_NAME` to see whether it
  528. hit that limit. Exit code 137 can also result from memory pressure on the k3d
  529. node or Docker VM; check `docker stats --no-stream` and the Docker Desktop
  530. memory allocation too.
  531. </details>
  532. <details>
  533. <summary><b>Agent runs but never answers, or its conversations and tool calls stay empty</b></summary>
  534. Both paths go through the host, so a loopback address in `.env` resolves to the
  535. pod itself. `AGENT_LITELLM_BASE_URL` must be
  536. `http://host.docker.internal:<litellm port>` — it's handed to the pod as
  537. `LITELLM_PROXY_TARGET` and used by the in-pod proxy on `:8090` that the runtime
  538. actually talks to. For empty activity, check ingest is reachable (see **Runtime
  539. telemetry** above).
  540. </details>
  541. <details>
  542. <summary><b>A base-image build crawls or times out fetching Debian packages</b></summary>
  543. The default archive CDN has likely handed you a degraded edge (seen at ~30KB/s,
  544. stalling the build for over an hour). Point the build at another full mirror — it
  545. must carry both `/debian` and `/debian-security`:
  546. ```bash
  547. APT_MIRROR=mirror.csclub.uwaterloo.ca bash docker/k3d/k3d-load-images.sh
  548. ```
  549. </details>
  550. ## Deploying to Kubernetes
  551. Requires a cluster with an ingress controller, a cert-manager `ClusterIssuer`, a
  552. `StorageClass`, and an OpenRouter API key. On your machine: `kubectl`, Helm 3,
  553. [Helmfile](https://helmfile.readthedocs.io/) `0.171.0` (the CI-pinned version),
  554. and the `helm-diff` plugin.
  555. ```bash
  556. cp .env.deploy.spec .env.deploy
  557. # replace every example image tag; fill in registry, passwords, hosts, and keys
  558. ./deploy.sh # kubectl apply of the deploy RBAC, then helmfile sync
  559. ```
  560. Helmfile brings up PostgreSQL (one instance each for the app, LiteLLM, and
  561. Firecrawl, and Hindsight), Redis, the LiteLLM proxy, Firecrawl, Hindsight, the API
  562. with its worker, communications gateway, memory gateway, and credential gateway, the UI, and a
  563. namespace-scoped Prometheus and Grafana. Hindsight's Helm hook generates its
  564. LiteLLM key automatically, using the same pattern as the application key; see
  565. [Agent Memory deployment](docs/guidelines/operations.md#agent-memory-deployment).
  566. Ordering, values, and secrets live in
  567. [`helmfile.yaml.gotmpl`](helmfile.yaml.gotmpl); the charts are in
  568. [`helm/`](helm/). Every option in `.env.deploy.spec` is commented.
  569. AAI Labs runs two deploy paths of its own on top of the same charts:
  570. `deploy.yml` ships every `staging`/`main` push to the k3s testing-ground cluster,
  571. and `deploy-public.yml` deploys a `vX.Y.Z` tag to the hosted public Talos
  572. cluster. It pushes API/UI images under that release tag and runtime images under
  573. their independent `VERSION` tags to `registry.agentbarn.dev`. A manual dispatch
  574. of `deploy-public.yml` takes an existing release tag, and its `skip_build` input
  575. reuses the explicitly tagged images already in the registry.
  576. Background:
  577. [`docs/architecture/runtime-and-deployment.md`](docs/architecture/runtime-and-deployment.md)
  578. and [`docs/guidelines/operations.md`](docs/guidelines/operations.md).
  579. ### Usage analytics
  580. Agent Barn installs send business events to Agent Barn's PostHog project (EU)
  581. by default (`ANALYTICS_ENABLED=true`). These are events such as an agent being
  582. created, started, or deleted, an organisation being created, updated, or deleted,
  583. a member joining an organisation,
  584. a user signing in or accepting an invite, and an hourly count of messages each
  585. agent received and sent. Each event carries random IDs (user, organisation, agent)
  586. and a name for your install, which defaults to your web app's host. It never
  587. carries agent or organisation names, prompts, message content, conversations,
  588. credentials, changed values, user email addresses, or full names. Users are
  589. identified by UUID, so the usage tracking is pseudonymous.
  590. To opt out, set `ANALYTICS_ENABLED=false` in `.env.deploy` and redeploy.
  591. Remote installs use the `WEB_APP_URL` hostname as their label; local installs use
  592. `local-<short UUID>`. The installation UUID remains stable when the URL changes. Local
  593. development stacks report too, as `installation_environment=local`; set
  594. `ANALYTICS_ENABLED=false` in your local `.env` to opt out. The full list of events and fields is in
  595. [`docs/features/product-analytics.md`](docs/features/product-analytics.md).
  596. ### Connecting agent email (manual step)
  597. Agents reachable by email receive mail through a Cloudflare Email Worker. CI
  598. deploys the Worker, but **it cannot connect the routing rule** — Email Routing
  599. rules are Cloudflare dashboard state with no Terraform or API step in this
  600. repository, so mail bounces until someone points the rule at the Worker by hand.
  601. Do this once per environment, in this order:
  602. 1. Merge to `staging`/`main`. The `deploy-worker` job publishes
  603. `agentbarn-email-inbound-<environment>`. The Worker must exist first — the
  604. routing rule's destination picker only lists deployed Workers.
  605. 2. In Cloudflare, go to **Email → Email Routing → Routing rules** and point the
  606. custom address `agent@<AGENT_EMAIL_DOMAIN>` at that Worker. One rule serves
  607. every agent, provided **subaddressing is enabled** under Email Routing →
  608. Settings — it is off by default, and while it is off every agent address
  609. bounces `550 5.1.1` with nothing in the activity log.
  610. 3. Only now delete any Worker you deployed with `wrangler --env local`. Deleting
  611. it while a rule still points at it bounces all inbound mail for that
  612. environment.
  613. Full setup — the two separate Cloudflare onboardings, the environment variables
  614. and secrets, quota limits, and secret rotation — is in
  615. [`docs/guidelines/operations.md`](docs/guidelines/operations.md#per-agent-email-addresses).
  616. ### Connecting OneDrive (manual step)
  617. Organizations can connect OneDrive from **Settings → Sync**, so Agent Barn keeps
  618. an "Agent Barn" folder in one of their SharePoint sites. It is optional and needs
  619. your own Microsoft app: until `ONEDRIVE_SYNC_CLIENT_ID` and
  620. `ONEDRIVE_SYNC_CLIENT_SECRET` are both set, Settings → Sync says "OneDrive is
  621. not configured for the platform." Do this once per install, in the Microsoft Entra
  622. admin center (needs the Application Administrator or Application Developer role):
  623. 1. **App registrations → New registration.** Choose **Accounts in any
  624. organizational directory (Multitenant)**. Single-tenant apps are refused,
  625. because Agent Barn signs in through Microsoft's shared `organizations`
  626. endpoint.
  627. 2. **Redirect URI:** platform **Web**,
  628. `<WEB_APP_URL>/api/v1/integrations/sync-provider/onedrive/callback`.
  629. Microsoft requires HTTPS unless the host is `localhost`.
  630. 3. **API permissions → Microsoft Graph:** application `Sites.Selected`;
  631. delegated `Sites.FullControl.All`, `Sites.Read.All`, `openid`, `profile`.
  632. 4. **Certificates & secrets → New client secret.** Copy the value at once and
  633. note its expiry; OneDrive connections stop working when it expires.
  634. 5. Put the app's **Application (client) ID** and the secret in `.env.deploy` as
  635. `ONEDRIVE_SYNC_CLIENT_ID` and `ONEDRIVE_SYNC_CLIENT_SECRET`, then redeploy.
  636. 6. A Microsoft Global Administrator of each organization that connects approves
  637. the app once (for your own organization: **API permissions → Grant admin
  638. consent**). An Owner or Admin who is a SharePoint Administrator then clicks
  639. **Connect** in Settings → Sync and picks a site.
  640. How connecting works, and its limits:
  641. [`docs/features/sync-provider/README.md`](docs/features/sync-provider/README.md).
  642. ## Repository layout
  643. | What | Where |
  644. | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
  645. | [`api/`](api/) | FastAPI control plane, ingest and communications apps, Dramatiq worker, migrations, tests |
  646. | [`ui/`](ui/) | Next.js App Router frontend |
  647. | [`helm/`](helm/) | Helm charts for every deployed service |
  648. | [`k8s/`](k8s/) | Cluster prerequisites the charts don't own |
  649. | [`hermes-base/`](hermes-base/), [`openclaw-base/`](openclaw-base/) | Agent runtime base images |
  650. | [`docker/`](docker/) | Local k3d cluster and image-loading scripts |
  651. | [`docs/`](docs/) | Architecture, feature, and decision records |
  652. | [`compose.yml`](compose.yml), [`run.sh`](run.sh), [`stop.sh`](stop.sh), [`Makefile`](Makefile) | Local development stack |
  653. | [`helmfile.yaml.gotmpl`](helmfile.yaml.gotmpl), [`deploy.sh`](deploy.sh) | Kubernetes deployment |
  654. Two dependencies live outside it: the Hermes and OpenClaw runtimes are upstream
  655. projects, and `aai-cli`, the tool the bundled skills drive, is built from a
  656. separate public AAI Labs repository at base-image build time. You can run and
  657. deploy the published base images without rebuilding them. The current local
  658. builder requires a GitHub token only to authenticate that public clone; it does
  659. not require private-source permission. Third-party components keep their own
  660. licences.
  661. ## Programmatic API
  662. Create a Personal API Key in Account settings to use the existing user-authenticated
  663. `/api/v1` routes. The deployed API serves an interactive reference at
  664. `/api/v1/docs`, an OpenAPI schema at `/api/v1/openapi.json`, and agent guidance
  665. at `/llms.txt`. See the [API quickstart](api/developer_docs/quickstart.md) for
  666. a Bearer-token example.
  667. ## Getting help and contributing
  668. Support, issue, discussion, and pull-request routes are collected in
  669. [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately by
  670. following [SECURITY.md](SECURITY.md).
  671. ## Licence
  672. Apache 2.0. See [LICENSE](LICENSE).
  673. Built by [AAI Labs](https://aai-labs.com) in Vilnius, Lithuania.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.