This guide walks you through cloning the repository, configuring your environment, and running the full local stack smoke test. By the end you will have four healthy Docker services running locally, a completed execution record in the database, and a full audit event trail you can inspect via the BFF API. The steps below reflect the Phase 0 acceptance criteria — everything here is tested and verified against the live stack.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.
Prerequisites
Ensure the following tools are installed and meet the minimum versions before proceeding.
The pnpm version is not installed globally. It is resolved by Corepack from the
| Tool | Minimum version | Notes |
|---|---|---|
| Docker | 24+ | Required for multi-stage builds and Compose v2 |
| Docker Compose | v2 | Bundled with Docker Desktop; verify with docker compose version |
| Node.js | 20+ | Required by harness-core (Astro SSR) |
| Python | 3.12+ | Required by runtime-python (FastAPI + RQ) |
| pnpm | 9+ | Resolved by Corepack — do not install globally |
packageManager field in the root package.json. You activate Corepack once per host; CI, Docker builds, and local development all inherit the same pinned toolchain automatically.Clone and configure the environment
Clone the repository and copy the environment template:Open The file also contains
.env and review the required variables before starting the stack. The core Phase 0 variables are:# PHASE 0.b and # PHASE 1 / # PHASE 2 sections with variables for mcp-auth-service, mcp-identity-connector, and model-gateway. Leave these at their defaults for a Phase 0 local run; they are either inert seams or already set to safe fallback values.Enable Corepack and install JavaScript dependencies
Activate Corepack once for the host, then install workspace dependencies using the pinned pnpm version:Corepack reads the
packageManager field in package.json (pnpm@10.33.0) and ensures every invocation — locally, in CI, and inside Docker — uses exactly that version. The pnpm install command materialises node_modules for all workspace packages under apps/.Start the local stack
Bring up all services in detached mode. Use either the convenience script defined in Docker starts all services in dependency order, pulling images for
package.json or the full Docker Compose command directly:postgres and redis and using previously built images for harness-core and runtime-python. Add --build to the direct docker compose invocation if you want to force a rebuild from the current source.runtime-python runs both the FastAPI server (uvicorn) and the RQ worker (rq worker executions) inside the same container, supervised by infra/docker/entrypoint.runtime-python.sh. There is no separate worker compose service in Phase 0 — splitting the worker is a future Phase 0.b / Phase 5 change.Verify stack health
Confirm all four services reached a healthy state:Expected output for a healthy Phase 0 stack:
Only
harness-core publishes a host port (0.0.0.0:4321->4321/tcp). runtime-python is internal-only and exposes port 8000 on the private Docker network only — never on the host. Do not attempt to curl localhost:8000 directly; health must be observed through the BFF or via Docker’s own healthcheck status.Check BFF health
Verify that the BFF is up and that it can reach A fully healthy response:If the runtime is still starting, you may see a degraded response:Wait a few seconds and retry. The
runtime-python on the private network:runtime-python healthcheck has a start_period of 15 seconds and retries every 5 seconds up to 10 times. Note that the response does not include a postgres field — PostgreSQL health is observed via docker compose ps, not through the BFF.Create your first execution
Submit a manual execution through the BFF API. The The BFF returns Save the
constraints object is part of every execution and controls the policy gate: allow_cloud: false ensures no data leaves the local network, and require_audit: true guarantees that audit events are written.201 Created with the new execution record:id value — you will use it in the next two steps.Poll for completion
The in-process RQ worker inside Replace Under normal conditions the transition completes within a few seconds. You can loop the call if you prefer:
runtime-python picks up the job from the Redis queue and transitions the execution through queued → running → completed. Poll until the status reaches completed:{id} with the UUID returned in the previous step. The response will show the current status:Inspect audit events
Retrieve the full event trail for the execution. The audit spec guarantees two events for every completed execution:Expected response:These events are written by the runtime’s
audit/event_builder.py — the runtime is the sole writer of audit_events. The BFF proxies the response without modification.The executions list and detail pages are also available in the browser at
http://localhost:4321/executions and http://localhost:4321/executions/{id}. The pages SSR-fetch from the BFF and do not query the database directly.The host-port boundary is a hard Phase 0 rule: only
harness-core publishes a port to the host (:4321). runtime-python is reachable exclusively on the private Docker network (harness-net). Never bind :8000 to the host or add any other service to the public network — this is a deliberate architectural constraint enforced at the compose level.