Harness AI is a self-hosted institutional agentic harness purpose-built for medium-sized municipal organizations (Gobiernos Autónomos Descentralizados and equivalent bodies). It acts as the central governance layer that stands between existing institutional systems — ERPs, document registries, expediente workflows, external channels — and the AI capabilities that operate on them. Every execution, model call, tool invocation, and identity decision passes through Harness AI, ensuring that no agentic action escapes policy control, audit recording, or authorization enforcement.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/joseluis-dev/harness-ai/llms.txt
Use this file to discover all available pages before exploring further.
The problem it solves
Municipal institutions cannot adopt off-the-shelf AI SaaS products without exposing sensitive citizen data to third-party clouds, accepting opaque billing models, or abandoning the compliance obligations that public-sector bodies carry. At the same time, rolling a fully custom AI platform from scratch is expensive and error-prone. Harness AI occupies the middle ground: it is a structured, opinionated harness that enforces institutional governance rules — fail-closed identity, full audit trails, centralized authorization, explicit tool registration — while remaining open enough to integrate with any existing municipal system through decoupled interfaces.Design principles
Harness AI is built around five non-negotiable principles that shape every architectural decision: Local-first execution. The model gateway starts with vLLM running on local hardware. External AI providers are only introduced in the final roadmap phase (Phase 13) and only under an explicit policy opt-in. No data leaves the institution’s infrastructure by default. Fail-closed identity. Every request resolves an actor context before proceeding. If identity resolution fails or is unavailable, the system degrades to a safeactor=system fallback on non-sensitive routes and blocks sensitive ones. There is no open-by-default path.
Centralized authorization. The mcp-auth-service is the single token authority for the entire harness. MCP servers, CLI wrappers, runtime workers, and webhook adapters all validate tokens through the shared auth-sdk. Distributed authentication — where each integration implements its own OAuth — is an explicit anti-pattern in the design.
Full audit by default. The audit_events table is written by the runtime on every state transition. The BFF is a thin façade that never writes to the database directly. Every execution has a complete lifecycle event trail from queued through running to completed (or failed).
Dynamic tool registry. Harness Core never enumerates tools in code. Every MCP server, CLI wrapper, HTTP adapter, and webhook integration is a row in the tool_registry. Adding a new tool means inserting a record — it does not mean modifying harness-core.
Dual database isolation
Harness AI enforces a hard boundary between two PostgreSQL instances that must never share a server:harness_dbholds business data:executions,audit_events,tool_registry,policy_library,model_prompts, embeddings, and RAG artifacts.harness_auth_dbholds the auth plane:oauth_clients,oauth_scopes,oauth_tokens,oauth_policies, andaudit_auth_events.
The 14-phase roadmap
The full roadmap runs from Phase 0 through Phase 13. Each phase is additive; no phase removes or replaces a previous one.| Phase | Name |
|---|---|
| 0 | Base executable local — monorepo, Docker stack, executions, audit |
| 1 | External identity integration — mcp-identity-connector |
| 2 | Local Model Gateway with vLLM or mock |
| 3 | MCP SQL readonly — first agentic tool |
| 4 | Document watcher and ingestion |
| 5 | Embeddings and basic RAG |
| 6 | Agent, tool, and policy administration (partial UI) |
| 7 | n8n webhooks integration |
| 8 | Secure Telegram channel |
| 9 | Human-in-the-loop approval flows |
| 10 | LangGraph for expediente workflows |
| 11 | Specialized institutional agents |
| 12 | Advanced observability |
| 13 | External AI providers (opt-in under policy) |
executions table, audit_events table, RQ worker — none of the intelligent capabilities have a safe place to execute.
Where to go next
Quickstart
Clone the repo, configure your environment, and bring up the local 4-service stack in minutes.
Architecture Overview
Understand how the seven services are organized, how networks are separated, and how requests flow through the harness.
Auth Model
Deep dive into the
mcp-auth-service, OAuth 2.1 Client Credentials flow, the auth-sdk, and harness_auth_db.Services and Networks
Production deployment topology: which services live on which Docker networks and which ports are — and are not — exposed.