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 organized as a multi-service Docker stack in which every component has a single, bounded responsibility. The system is designed so that external systems — human users, n8n automations, expediente workflows, ERP integrations — always enter through a single public entrypoint (harness-core), and all downstream services operate exclusively on a private Docker network. This separation is not a preference: it is enforced by the compose topology, and deviating from it is a deployment constraint violation.

​
Service inventory

The full target stack consists of seven services. Phase 0 brings up the first four; subsequent phases add the remaining services as additive layers.
ServiceTechnologyRoleHost port
harness-coreAstro SSR + @astrojs/node (Node 20+)BFF — public entrypoint, policy enforcement, execution API, UI:4321
runtime-pythonFastAPI 0.115 + Pydantic v2 + SQLAlchemy async + RQ workerExecution engine, job queue consumer, audit writer, RAG, tool resolutionNone (internal)
model-gatewayFastAPILocal-first model routing (mock → vLLM → cloud under policy)None (internal)
mcp-auth-serviceOAuth 2.1 Client Credentials, JWKS, introspectionCentral token authority for all tools, MCPs, CLI wrappers, and webhooksNone (internal)
postgresPostgreSQL 16harness_db — business data: executions, audit_events, tool_registry, policy_library, embeddingsNone (internal)
postgres-authPostgreSQL 16harness_auth_db — auth plane: oauth_clients, oauth_scopes, oauth_tokens, oauth_policies, audit_auth_eventsNone (internal)
redisRedis 7RQ broker and operational cacheNone (internal)
Phase 0 starts four services: postgres, redis, runtime-python, and harness-core. model-gateway is added in Phase 2. mcp-auth-service and postgres-auth seams are present in the compose file from Phase 0.b onward but are not active until Phase 0.b PR-2 wires them in.

​
Network topology

Harness AI uses a single private Docker bridge network (harness-net) for inter-service communication. Only harness-core additionally publishes a port to the host. 
┌─────────────────────────────────────────────────────┐
│                  HOST / Public                       │
│   External systems, browsers, n8n, CLI operators    │
└───────────────────────┬─────────────────────────────┘
                        │ :4321 (only published port)
                        ▼
┌─────────────────────────────────────────────────────┐
│              harness-core (BFF)                     │
│              Astro SSR · Node 20+                   │
└──────┬─────────────┬──────────────┬─────────────────┘
       │             │              │
       │ (harness-net — private Docker network)
       ▼             ▼              ▼
┌─────────────┐ ┌──────────┐ ┌──────────────────────┐
│runtime-python│ │  redis   │ │    model-gateway      │
│ FastAPI + RQ │ │ broker   │ │  FastAPI (local-first)│
└──────┬──────┘ └──────────┘ └──────────────────────┘
       │
       ▼
┌─────────────┐   ┌──────────────────┐
│  postgres   │   │  postgres-auth   │
│ harness_db  │   │ harness_auth_db  │
└─────────────┘   └──────────────────┘
The harness-net bridge is the only network defined in the compose files. No service other than harness-core has a ports: mapping. This means runtime-python, model-gateway, mcp-auth-service, postgres, postgres-auth, and redis are unreachable from the host by design. Health for internal services is observed through Docker’s own healthcheck: directives and through the BFF’s aggregate /api/healthz endpoint.

​
Request flow

A typical execution request travels through the following path from the external caller to the first tool invocation: 
External system (human, n8n, webhook)
        │
        │  POST /api/executions   (HTTP, port 4321)
        ▼
harness-core (BFF)
  · Validates request schema (Zod)
  · Resolves actor identity (via mcp-identity-connector or fallback)
  · Enforces constraints (allow_cloud, require_audit, risk_level)
  · Enqueues job via Redis (RQ queue: "executions")
  · Returns 201 { id, status: "queued" }
        │
        │  RQ job dequeued
        ▼
runtime-python (in-process RQ worker)
  · Transitions execution: queued → running  (writes audit_event)
  · Resolves tool by name from tool_registry
  · Calls mcp-auth-service to obtain a scoped Bearer token
  · Dispatches tool call (MCP server / CLI wrapper / HTTP adapter)
  · Transitions execution: running → completed (writes audit_event)
        │
        ▼
mcp-auth-service
  · Issues OAuth 2.1 Client Credentials token
  · Validates client is in state=active
  · Persists token record in harness_auth_db
        │
        ▼
Tool execution (MCP server / CLI / HTTP API)
  · Validates Bearer token via auth-sdk
  · Executes operation within sandboxed scope
  · Returns result to runtime-python
The BFF (harness-core) is a thin façade: it never writes to harness_db directly. Every database write — executions, audit_events — is performed by runtime-python. This separation is a design invariant enforced across all phases.

​
Dual database isolation

The two PostgreSQL instances serve fundamentally different planes and must never share a server: harness_db (business and audit plane) Managed by runtime-python via SQLAlchemy async. Contains:
  • executions — lifecycle records for every agentic job
  • audit_events — immutable event trail written on every state transition
  • tool_registry — dynamic registry of all MCP servers, CLI tools, HTTP adapters, and webhooks
  • policy_library — governance rules evaluated before each execution
  • model_prompts — versioned prompt templates
  • pgvector embeddings and RAG indexes
harness_auth_db (auth and permissions plane) Managed exclusively by mcp-auth-service. Contains:
  • oauth_clients — registered technical clients (harness-core, runtime, admin panel, n8n, etc.)
  • oauth_scopes — available scopes and their risk classifications
  • oauth_tokens — active and revoked Bearer tokens
  • oauth_policies — per-client token issuance policies
  • audit_auth_events — auth-plane audit trail (separate from business audit)
harness_db and harness_auth_db must run on separate PostgreSQL container instances with separate credentials and separate Docker volumes. Pointing both HARNESS_DATABASE_URL and MCP_AUTH_DATABASE_URL at the same Postgres instance is a deployment constraint violation. This separation exists from the first commit — it is not a future optimization.

​
Separation of concerns

The architecture enforces explicit boundaries on what each component is and is not allowed to do:
ComponentMust NOT do
harness-core (BFF)Enumerate MCPs, CLIs, or APIs in code; write directly to harness_db; authenticate external clients by itself
mcp-auth-serviceKnow or apply business logic; issue tokens to clients in state != active
MCP servers / CLI wrappersImplement their own OAuth; receive raw database connection strings from agents
tool_registryContain authorization logic; it resolves tools by name but does not authorize their use
Admin panel (Astro)Expose secrets to the browser; use static-only output for dynamically mutating internal views
These boundaries mean, for example, that adding a new integration never requires changing harness-core: the integration is registered as a new row in tool_registry, and the runtime resolves it by name at execution time.

​
Deeper dives

System Purpose

The full governance mandate: why Harness AI exists, what institutional problems it solves, and the design invariants that flow from the municipal context.

Auth Model

OAuth 2.1 Client Credentials flow, the mcp-auth-service contract, auth-sdk usage in MCP servers and CLI wrappers, and the harness_auth_db schema.

Tool Registry

How tools are registered, resolved by name, versioned, and activated/deactivated without modifying harness-core. Covers MCP, CLI, HTTP, and webhook tool types.

Harness Core

Implementation detail for the BFF: Astro SSR route structure, the execution API contract, identity resolution, constraint enforcement, and the UI execution pages.

Build docs developers (and LLMs) love

Get started for freeTalk to us