Skip to main content

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.

Harness AI is a self-hosted institutional agentic harness designed for municipal and governmental organizations that need strict governance over every AI action taken within their infrastructure. Rather than exposing raw model APIs or allowing unconstrained agent behavior, Harness AI acts as the central authority between institutional systems — expedientes, ERPs, document repositories, identity providers — and the AI capabilities that operate on them. Every request, whether it originates from a human through the web portal, an n8n automation, or an internal workflow, must traverse the harness before reaching any tool, model, or data source.

​
Core Objectives

The harness is built to fulfill a comprehensive set of institutional responsibilities from a single, unified control plane:

Governance & Policies

All agents, workflows, tools, and models are governed by declarative policies. No agent operates outside the harness boundary.

Security & Auditing

Every action records actor, agent, tool, model, parameters, result, and timestamps in an append-only audit ledger from Phase 1, not as a future enhancement.

Permissions & Authorization

Centralized OAuth 2.1 Client Credentials flow via mcp-auth-service. Scopes and risk levels govern what each client can invoke.

Orchestration

Harness Core coordinates agents, workflows, and approval gates. MCP is a tool-exposure protocol, not the orchestrator.

Tool Integration

MCP servers, CLI wrappers, HTTP/webhook adapters — all discovered dynamically from the tool_registry. No hardcoded lists in core.

Document Processing & RAG

File watchers detect new institutional documents and vectorize them into pgvector. Documents never need to be uploaded manually as a primary workflow.

Local AI Execution

vLLM serves local models. External AI providers are only integrated in final phases, under explicit policy, never as default dependencies.

Human Approval

Destructive, administrative, and external-side-effect operations route through human approval gates before execution proceeds.

Interoperability

Integrations with municipal systems happen through adapters, MCPs, controlled CLIs, webhooks, and connectors — never through rigid in-core coupling.

​
Non-Negotiable Principles

Five architectural principles govern every technical decision in Harness AI. No component, agent, or workflow may contradict them.

​
Local-First

The system operates first with local models and internal data. External AI providers such as OpenAI, Claude, or Gemini are reserved for final phases and require explicit policy to enable. Implications:
  • The design does not depend on external API keys at startup.
  • Sensitive institutional documents never leave the local environment.
  • vLLM is the initial recommended engine for local model serving.
  • The Model Gateway exists from early phases but initially routes only to local models.

​
Harness as Governance Layer — Fail-Closed

The harness is the institutional authority. No agent, MCP, CLI, model, worker, or workflow bypasses it. The system is fail-closed by design: any request that cannot be positively authorized — because a client is not active, a tool is disabled or deprecated, a scope is missing, or the auth service is unreachable — is denied before execution proceeds. There is no permissive fallback. Permitted flow: 
User / External System
  → Harness
  → Policy
  → Authorized Agent / Workflow
  → Authorized MCP / CLI Tool
  → Audit
  → Result
Prohibited flows: 
User → MCP directly
User → CLI directly
n8n → sensitive database directly
LLM → free shell command
LLM → tool without authorization
External system → AI model directly with sensitive data

​
Decoupled Integration

The harness connects to other systems through:
  • Internal APIs and webhooks (signed)
  • MCP servers
  • Controlled CLI wrappers
  • Directory watchers
  • Queues, adapters, and connectors (SQL read-only, identity, documents, expedientes, notifications)
No rigid institutional logic is embedded in core.

​
Complete Audit

Every action records:
  • Origin user or system
  • Agent used
  • Tool invoked
  • Model used
  • Prompt and version references
  • Parameters and result
  • Errors
  • Documents consulted
  • SQL queries when applicable
  • Policy decision
  • Human approval when applicable
  • Timestamps and correlation IDs (request/execution)

​
Separation of Responsibilities

Each component has a fixed scope. The table below captures what each must not do — enforced from the first commit.
ComponentMust NOT do
Harness CoreEnumerate MCPs, CLIs, or APIs in code; authenticate clients independently.
mcp-auth-serviceContain business logic; emit tokens for clients whose state != active.
MCP servers / CLI wrappersImplement their own OAuth; receive connection strings from agents.
tool_registryContain authorization logic; be bypassed as the resolution point.
Admin Panel (Astro)Expose secrets to the browser; use static-only output for dynamic internal views.
Prohibited anti-patterns — enforced at code review
  • Auth by MCP: Any MCP server, CLI wrapper, or HTTP adapter that implements its own OAuth flow instead of delegating to auth-sdk is an automatic PR rejection.
  • Tokens in query string: Access tokens must only travel in the Authorization: Bearer header. A token appearing in a URL query parameter violates this principle unconditionally.
  • Mixing harness_db and harness_auth_db: The two PostgreSQL databases are on separate Compose services with separate volumes and separate Alembic version tables (alembic_version vs alembic_version_auth). Any migration or query that crosses this boundary is prohibited from the first commit.

​
Implementer Rules

The following twelve rules govern how Harness AI is built and extended. They apply to every contributor and every phase of implementation.
1

Implement by phases

Do not build all capabilities at the same time. Each phase must leave something executable and deployable with Dokploy.
2

Prioritize local operation

External AI providers are reserved for final phases. Never make the early phases depend on external API keys.
3

No free agents

Every agent, tool, model, workflow, and action must be governed by the harness. No component operates outside it.
4

No coupling to specific municipal systems

Every integration uses adapters, MCPs, controlled CLIs, webhooks, or explicit connectors. No municipal system logic is hardcoded in core.
5

No assumed internal auth at startup

Authentication and user management reside in an existing institutional system. The harness integrates with it via a connector, not by implementing it.
6

No manual document upload as primary flow

Document ingestion happens from other institutional systems. The harness observes configured directories, detects new or modified files, and vectorizes them.
7

n8n is not the system brain

n8n integrates only via signed webhooks for external automations, notifications, and triggers. It has no direct authority over the harness.
8

LangGraph only for complex flows

Use LangGraph only for stateful workflows with multiple steps, decisions, retries, or human intervention. It is not the default execution path.
9

MCP is not the main orchestrator

MCP exposes tools. The harness governs and orchestrates.
10

No free CLI execution

Every CLI command must be explicitly permitted, parameterized, audited, isolated, and controlled. No shell commands generated freely by LLMs.
11

Audit from phase one

The audit ledger is a base requirement, not a future improvement. It ships in Phase 1.
12

Design for production from the start

Every phase must produce something that can be deployed to production with Dokploy.

​
Architecture at a Glance

Two entry paths converge at Harness Core: institutional systems via APIs, MCP, CLIs, and webhooks; and documents arriving through watched directories. The Astro BFF is the only public human-facing entrypoint and never authenticates external clients on its own — it delegates entirely to mcp-auth-service. From Harness Core, three execution paths branch out:
  • MCP Gateway — resolves tools from tool_registry and invokes MCP servers over HTTP, validating Bearer tokens via auth-sdk.
  • CLI Runner — invokes deterministic CLI wrappers from an allowlist, enforcing execution restrictions declared in tool_registry.
  • LangGraph Runtime — executes complex stateful workflows with human approval gates.
All three paths bottom out at mcp-auth-service, the single token authority, backed by harness_auth_db — a PostgreSQL instance that is always independent of harness_db.
The Model Gateway below mcp-auth-service is local-first: vLLM serves local models initially. External cloud providers are integrated only in final phases under explicit policy.

Build docs developers (and LLMs) love

Get started for freeTalk to us