Skip to the content.

CLike Orchestrator

FastAPI service that owns the Harper domain: phase semantics and contracts, execution policy (cloud vs local agent), local-agent execution packages, eval runner and gate, RAG API and the read-only MCP server. It delegates model calls to the gateway.

Layout

Path Content
app.py Application, authentication middleware, MCP mount
routes/ harper.py (/v1/harper/*), v1.py (chat, generate, models), routes_eval.py (eval/gate), rag.py, agent.py, router.py, health.py
services/harper.py Phase pipeline (run_phase), contracts, KIT stages
services/local_agent/ Execution packages for local agents, one module per phase (local_agent_package.py is a compatibility facade)
phases/ Phase definitions as data: phase.yaml, text.yaml, cloud prompts
services/cloud_prompt/, services/phase_context.py Cloud phase messages composed for the gateway; typed PhaseContext
services/context_sources.py, services/extend_cascade.py Project context sources and release folders; /idea --extend cascade rules
services/kit_repair.py, services/gate_integrity.py, services/finalize_verify.py Auto-eval repair, acceptance lock and amendments, /finalize verification
services/methodologies/ Methodology profiles (BMAD resolver, quality contracts)
eval_runner.py Deterministic execution of LTC profiles, regression of promoted REQs
eval_environment.py Eval environment provisioning (variables, test databases, services)
eval_sandbox_app.py, eval_tools_app.py, eval_tools_catalog.yaml Eval sandbox and eval tools services (own containers, same image)
mcp_server.py Read-only MCP tools
utils/service_auth.py, utils/safe_paths.py Service authentication and path confinement
tests/ Unit, contract, security and golden-snapshot tests

Run

uv sync --frozen
CLIKE_API_TOKEN=… DEV_FOLDER=/path/to/projects GATEWAY_URL=http://127.0.0.1:8000 \
  uv run uvicorn app:app --host 127.0.0.1 --port 8080 --reload
uv run pytest -q

In containers see ../docs/setup-and-runtime.md.

Security-relevant configuration

Variable Purpose
CLIKE_API_TOKEN Required. Bearer token for every endpoint except /health; also sent on calls to the gateway
CLIKE_ALLOWED_HOSTS Accepted Host names (default localhost,127.0.0.1,::1,gateway,orchestrator)
DEV_FOLDER, CLIKE_EVAL_ALLOWED_ROOTS Roots under which eval/gate may operate
CLIKE_ALLOW_INLINE_LTC 1 to accept inline-only LTC profiles (default: workspace file is authoritative)
CLIKE_MCP_SERVER_ENABLED Mount the MCP server at /mcp (token-protected)
CLIKE_EVAL_SANDBOX_URL, CLIKE_EVAL_TOOLS_URL Eval sandbox and eval tools services (unset: in-process eval, no tool installs)

API

See ../docs/api-reference.md and ../docs/mcp.md.