Harness

Ship code with a fleet of AI agents you can actually trust — orchestrated, policed, reviewed, and observable.

Documentation · Contributing · Security

---

AI development is no longer one agent in one terminal — it is fleets of agents working in parallel across issues, branches, and repositories. The hard problems move up a level: who assigns the work, what each agent is allowed to do, who reviews the output, and what happens when a run goes wrong at 3 a.m.

Harness is a Rust-native control plane for that fleet. It wraps AI coding agents (Claude Code, Codex, Anthropic API) with structured lifecycle management, policy enforcement, and continuous feedback loops. Instead of replacing agents, it standardizes how they run, what they're allowed to do, and how their output is reviewed.

Find the right workflow

This project is majiayu000/harness, the Rust coding-agent control plane. The similarly named Agent Harness is a Claude Code plugin for GitHub issue delivery; the projects have different installation and operation paths.

Your task	Start here	Prerequisite or boundary
Run one coding-agent task	Single-agent quickstart	Docker, the runtime/proxy images, and explicit provider credentials and hosts. No fleet server is needed.
Operate a fleet and dashboard	Fleet setup	Postgres and API authentication; the server is separate from a one-shot command.
Submit work through the runtime	Submission API and API contract	Submit the registered project/workflow rather than treating legacy tasks as the runtime API.
Recover a stopped workflow	Workflow runtime operations	Inspect the pinned definition, stop reason, and recovery conditions before resuming.
Isolate untrusted issue intake	Container-tier operator guide	Docker, pinned images, and explicit credential/network scope.
Inspect execution evidence	OpenTelemetry trajectory quickstart	Configure the documented telemetry path; a submission alone does not prove completion.

Use Issues for reproducible failures with the source revision, runtime, selected sandbox, and redacted evidence. This repository builds from source; Releases and release instructions define publication separately from CI. The source is licensed under MIT.

Install

Build from source (no prebuilt binaries or Homebrew formula yet):

git clone https://github.com/majiayu000/harness.git
cd harness
cargo build --release -p harness-cli
# binary at ./target/release/harness

Requires Rust 1.88+. A fresh release build also requires Bun 1.3.14 (the version pinned in .bun-version and tested in CI) because it embeds the web dashboard; if web/dist is already built, the release build can reuse it without Bun. Postgres and an API authentication token are only needed for the server / fleet features below; a GitHub token is additionally needed for GitHub integration.

On Linux, also install a C compiler/linker, pkg-config, and OpenSSL development headers/libraries for the default native-TLS dependencies. On Debian/Ubuntu, these are provided by build-essential, pkg-config, and libssl-dev. The OpenSSL command-line program alone does not provide the development headers.

Quickstart: run one agent task

Provider connectivity is an explicit prerequisite. The default capability_profile = "standard" is scoped, and an empty isolation.network_allowlist denies all agent networking, including model requests. Installing or authenticating a CLI alone does not enable provider access. Keep the scoped profile and list the exact hosts your selected provider uses; changing --sandbox-mode does not override this network policy.

The following first-task path uses Claude in a container on Linux or macOS. It needs Docker Engine and a provisioned Anthropic API credential. It needs neither Postgres nor the fleet server. Use a Bash terminal and run from this checkout:

# Verify the bundled coding-runtime image, then build the first-party proxy.
scripts/verify-agent-container-image.sh
docker build -f docker/egress-proxy/Dockerfile \
  -t harness-egress-proxy:quickstart docker/egress-proxy
export HARNESS_AGENT_CONTAINER_IMAGE="$(docker image inspect harness-agent:fixture --format '{{.Id}}')"
export HARNESS_AGENT_EGRESS_PROXY_IMAGE="$(docker image inspect harness-egress-proxy:quickstart --format '{{.Id}}')"

# The tracked template explicitly selects standard permissions and container.
# Harness expects a complete TOML config, not a partial override file.
sed 's/^network_allowlist = .*/network_allowlist = ["api.anthropic.com"]/' \
  config/default.toml.example > harness-first-task.toml

# Read the credential without echoing it or saving it in TOML/history.
read -r -s -p 'Anthropic API key: ' ANTHROPIC_API_KEY
printf '\n'
export ANTHROPIC_API_KEY

./target/release/harness --config harness-first-task.toml exec --agent claude \
  --output-file first-task.md \
  "Summarize the public API exposed by crates/harness-core/src/lib.rs"

Harness forwards the explicitly provisioned ANTHROPIC_API_KEY to the Claude container by environment variable name. An API key, an allowlist, and a usable runtime image are separate prerequisites. A successful image fixture proves packaging, not provider authentication or task completion. Inspect the command's exit status and first-task.md; a dispatch or healthy server alone does not prove the task completed. Production deployments should use registry digests for both images. See the operator guide for platform support, provider setup, and refusal diagnostics.

Platform and tier	Scoped provider access
Linux container	Supported through the bundled allowlist proxy; use this for online coding tasks.
Linux host	Empty allowlist denies networking. A non-empty allowlist is rejected; use container.
macOS container	Supported through the bundled allowlist proxy, as above.
macOS host	Proxy routing uses a loopback port and Seatbelt; runtime startup compatibility must also be checked. Docker is required for the proxy.

On macOS 26.5.2 (25F84), Codex CLI 0.162.1 aborted under Harness's read-only host Seatbelt wrapper with failed to allocate a guard page: Invalid argument (os error 22). Even codex --version failed under that wrapper while the same binary succeeded outside it. This startup result covers that specific OS/runtime/sandbox combination; it does not establish provider authentication or support for other combinations. Use the container quickstart above for Claude without broadening permissions.

For a locally installed and authenticated Codex CLI with verified macOS host startup compatibility, build the proxy as above and use a separate host configuration. This example assumes Codex uses an API provider at api.openai.com; configure the exact endpoints for your actual authentication/provider mode, including any required authentication hosts. A ChatGPT login or custom gateway can require a different host list.

sed -e 's/^default_tier = .*/default_tier = "host"/' \
  -e 's/^network_allowlist = .*/network_allowlist = ["api.openai.com"]/' \
  config/default.toml.example > harness-codex-host.toml

./target/release/harness --config harness-codex-host.toml exec --agent codex \
  "Summarize the public API exposed by crates/harness-core/src/lib.rs"

Run Harness as an unprivileged OS user: --drop-sudo defaults to true, so harness exec rejects root and sudo environments. The default exec sandbox is workspace-write. Linux host deny-all sandboxes require harness-landlock or bwrap; specifically, danger-full-access with scoped deny-all networking requires Bubblewrap. Claude and OpenCode cannot use the macOS host Seatbelt workspace-write path; use the container path above for Claude instead of broadening permissions.

The anthropic-api adapter generates text without repository context or tools, so it cannot inspect or modify the project in this coding example. OpenCode is provider-agnostic; provision its runtime authentication and provider hosts before using it.

Useful flags: --project <dir>, --agent claude|codex|anthropic-api|opencode, --model <id>, --sandbox-mode <mode>, --output-file result.md. Supported sandbox modes are read-only, read-only-with-network, workspace-write, and danger-full-access; they do not grant an exception to the configured egress policy.

Level up: the fleet control plane

For parallel agents, task queues, cross-agent review, and the web dashboard, start the server (needs Postgres 14+, an API bearer token, and Docker Engine with the Docker Compose v2.1+ plugin for the bundled database). The copy-paste token generation below also needs the OpenSSL CLI. The Codex-safe launcher additionally requires curl and lsof.

In a normal standalone terminal, start Postgres and the foreground server:

# Terminal 1
HARNESS_API_TOKEN="$(openssl rand -hex 32)" &&
  test -n "$HARNESS_API_TOKEN" &&
  export HARNESS_API_TOKEN &&
  printf '\nCopy this command into every client terminal:\n  export HARNESS_API_TOKEN=%s\n\n' \
    "$HARNESS_API_TOKEN" &&
  bash scripts/dev-db.sh &&
  ./start-server.sh

From a Codex-owned session, use the sanitized launcher instead; it removes wrapper variables that can confuse child Codex agents. This environment-based quickstart selects its background nohup path so the database and authentication settings reach the server even when another tmux server already exists:

HARNESS_API_TOKEN="$(openssl rand -hex 32)" &&
  test -n "$HARNESS_API_TOKEN" &&
  export HARNESS_API_TOKEN &&
  printf '\nCopy this command into every client terminal:\n  export HARNESS_API_TOKEN=%s\n\n' \
    "$HARNESS_API_TOKEN" &&
  bash scripts/dev-db.sh &&
  export HARNESS_DATABASE_URL=postgres://harness:harness@localhost:5432/harness &&
  export HARNESS_DATABASE_POOL_MAX_CONNECTIONS=16 &&
  export HARNESS_DATABASE_POOL_ACQUIRE_TIMEOUT_SECS=60 &&
  HARNESS_STARTER_NO_TMUX=1 bash scripts/start-harness-codex-safe.sh

For the standalone path, start-server.sh remains in the foreground, so check it from a second terminal. First paste the exact export HARNESS_API_TOKEN=... command printed by Terminal 1, then verify both the unauthenticated health endpoint and an authenticated API endpoint:

# Terminal 2
# Paste the export command printed by Terminal 1 before running these commands.
curl http://127.0.0.1:9800/health
curl http://127.0.0.1:9800/api/dashboard \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}"

Open http://127.0.0.1:9800/ and enter the same token when the dashboard prompts for it. The token grants API access; treat the printed command as a secret and do not commit or share it. Shell environments are not shared between terminals or persisted across restarts; after restarting, use the newly printed export command.

The Console v3 dashboard provides nine views with live submissions, approvals, events, usage, projects, and runtime state. See Console v3 for supported actions, data sources, and backend limitations.

Full server setup, configuration, and workflows are covered in Quick Start below.

Key Features

• Fleet orchestration — Run many agents in parallel with a unified task/thread/turn lifecycle; pluggable adapters for Claude Code CLI, Codex CLI, and Anthropic API
• Independent agent review — Automatic cross-agent code review between implementation and GitHub review, preventing self-review by architecture
• Policy engine — Starlark-based execution policies with hardened parser dialect (no load/def/lambda) for sandboxed rule evaluation
• Signal-driven GC — Detects repeated warnings, chronic blockers, and hot files; generates and adopts remediation drafts within configurable budgets
• GitHub webhook automation — HMAC-SHA256 verified webhooks parse @harness mentions to trigger tasks from issue comments and PR reviews
• OpenTelemetry export — Native OTLP/HTTP/gRPC traces and metrics with async-safe transport for signal-handler contexts
• MCP server mode — JSON-RPC stdio interface exposing harness tools as an MCP-compatible server
• CI/CD GitHub Action — Workspace-bound execution with path traversal protection and privilege enforcement

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Harness CLI                          │
│              serve · exec · gc · rule · skill               │
├──────────┬──────────┬───────────────────────────────────────┤
│  stdio   │   HTTP   │  WebSocket   │  MCP Server  │ Webhook│
├──────────┴──────────┴──────────┴───┴──────────────┴────────┤
│                    JSON-RPC Router (30 methods)             │
├────────────┬─────────────┬────────────┬────────────────────┤
│   Threads  │    Tasks    │   Turns    │    ExecPlans       │
├────────────┴─────────────┴────────────┴────────────────────┤
│  harness-agents    │  harness-rules   │  harness-skills    │
│  (Claude/Codex/API)│  (Starlark exec) │  (discovery/dedup) │
├────────────────────┼──────────────────┼────────────────────┤
│  harness-gc        │  harness-observe │  harness-exec      │
│  (signal/drafts)   │  (events/OTLP)  │  (plan lifecycle)  │
├────────────────────┴──────────────────┴────────────────────┤
│                    harness-core                             │
│          config · prompts · domain types · traits           │
├────────────────────────────────────────────────────────────┤
│                    harness-protocol                         │
│       JSON-RPC envelopes · method definitions · codecs      │
└────────────────────────────────────────────────────────────┘
        ▼               ▼                ▼
   Claude Code CLI   Codex CLI    Anthropic API

Quick Start

CLI install and one-shot execution are covered in Install and Quickstart above. This section covers the server and development setup.

Server prerequisites

• Bun 1.3.14 (the version pinned in .bun-version and tested in CI) for release builds that embed the web dashboard. If web/dist is already built, release builds can reuse it.
• Postgres 14+. For local development, scripts/dev-db.sh starts the bundled Postgres service and requires Docker Engine with the Docker Compose v2.1+ plugin (docker compose, not legacy docker-compose v1).
• A GitHub token for issue/PR automation. Use gh auth login, GITHUB_TOKEN, GH_TOKEN, or server.github_token.

Rust API Facade

For Rust consumers inside the repository or embedded integrations, harness-api provides a curated stable import surface over the lower-level crates:

use std::path::Path;

use harness_api::core::SessionId;
use harness_api::exec::ExecPlan;
use harness_api::protocol::INTERNAL_ERROR;
use harness_api::sandbox::{SandboxMode, SandboxSpec};

let _session = SessionId::new();
let _plan = ExecPlan::from_spec("# Demo", Path::new(".")).expect("plan");
let _sandbox = SandboxSpec::new(SandboxMode::ReadOnly, ".");
let _code = INTERNAL_ERROR;

The facade groups the stable parts of harness-core, harness-protocol, harness-sandbox, and harness-exec under one crate without forcing callers to track internal crate layout changes.

Database Setup

Harness requires Postgres 14+ (SQLite was removed in v0.x). Configure server.database_url in your TOML config or set HARNESS_DATABASE_URL before starting the server. When no config or environment database URL is present, ./start-server.sh uses the local development default postgres://harness:harness@localhost:5432/harness. Migrations run automatically on first connect.

Option A — Docker Compose (recommended for local dev):

# Start Postgres container (idempotent — safe to re-run)
bash scripts/dev-db.sh

# Then set `server.database_url = "postgres://harness:harness@localhost:5432/harness"`
# in your config file (for example `config/default.toml`).

Option B — docker compose directly:

docker compose up -d postgres
# Then set `server.database_url = "postgres://harness:harness@localhost:5432/harness"`
# in your config file.

Option C — existing Postgres instance:

Set server.database_url to any existing Postgres 14+ instance:

[server]
database_url = "postgres://user:password@host:5432/dbname"

Running tests against a real database:

createdb harness_test
HARNESS_DATABASE_URL=postgres://harness:harness@localhost:5432/harness_test cargo test --workspace

Integration tests that require a database (e.g. runtime_state_store, thread_db, q_value_store) skip automatically when no Harness database URL is configured. Postgres-backed tests reject non-test database names by default; use harness_test, a name ending in _test, or a name starting with test_. For intentionally disposable databases with a different name, set HARNESS_ALLOW_NON_TEST_DATABASE_FOR_TESTS=1.

Harness-server validation ladder:

# Routine server work: fast module and lightweight route path.
HARNESS_DATABASE_URL=postgres://harness:harness@localhost:5432/harness_test scripts/test-server-fast.sh

# Full server DB, startup, recovery, route, and workflow profile.
HARNESS_DATABASE_URL=postgres://harness:harness@localhost:5432/harness_test scripts/test-server-db.sh

# Optional nextest runner for the same DB-capable profile.
HARNESS_SERVER_TEST_RUNNER=nextest HARNESS_DATABASE_URL=postgres://harness:harness@localhost:5432/harness_test scripts/test-server-db.sh

# Final PR handoff: full workspace coverage.
HARNESS_DATABASE_URL=postgres://harness:harness@localhost:5432/harness_test cargo test --workspace

scripts/test-server-fast.sh is the warm local feedback path for routine harness-server changes once a test database URL is configured. scripts/test-server-db.sh runs the full server suite with default test parallelism. DB-backed tests rely on unique temporary data directories or explicit TestSchemaGuard schemas. Tests that mutate true process-global state, such as HOME, keep their own named locks.

Run

HTTP server:

bash scripts/doctor.sh
./start-server.sh
curl http://127.0.0.1:9800/health

scripts/doctor.sh is non-mutating. It checks database URL resolution and Postgres reachability, the release binary/build prerequisite, GitHub token discovery, webhook secret readiness when webhook intake is enabled, local agent CLI availability, required WORKFLOW.md runtime flags, port occupancy, and unsafe non-local HTTP exposure before you start the server. Use scripts/doctor.sh --dry-run when you want a report without a failing exit code.

./start-server.sh selects HARNESS_CONFIG, config/default.toml, config/claude.toml, a user config file, or built-in defaults in that order. It verifies the HTTP port, starts the local Docker Compose Postgres service when using the local fallback URL, loads GITHUB_TOKEN from gh auth token when available, and builds ./target/release/harness with cargo build --release -p harness-cli if the release binary is missing.

harness serve persists its runtime log under server.data_dir/logs/ as harness-serve-<startup-timestamp>-pid<PID>.log. /health exposes a redacted runtime_logs.path_hint, while /api/operator-snapshot includes the full active path for operators. Startup cleanup removes matching runtime logs older than observe.log_retention_days and prunes the oldest extra matching logs beyond observe.log_retention_max_files; set the max-files value to 0 for age-only retention.

Stdio (for MCP integration):

cargo run -p harness-cli -- serve --transport stdio

One-shot execution:

cargo run -p harness-cli -- exec \
  "Summarize the public API exposed by crates/harness-core/src/lib.rs"

Common Workflows

The protected HTTP examples assume HARNESS_API_TOKEN is exported in the client shell as shown in the server quickstart above.

# Workflow-runtime submission
curl -X POST http://127.0.0.1:9800/api/workflows/runtime/submissions \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add input validation to the API handler"}'

# Rule engine
cargo run -p harness-cli -- rule load .
cargo run -p harness-cli -- rule check .

# GC cycle — detect signals and generate remediation drafts
cargo run -p harness-cli -- gc run .

# Skill discovery
cargo run -p harness-cli -- skill list

# ExecPlan lifecycle
cargo run -p harness-cli -- plan init ./spec.md
cargo run -p harness-cli -- plan status ./exec-plan-<id>.md

Configuration

All settings are declarative TOML. Pass --config <path> or copy the tracked config/default.toml.example to config/default.toml and adjust it for your environment.

[server]
transport = "stdio"
http_addr = "127.0.0.1:9800"
data_dir = "~/.local/share/harness"
project_root = "."
# Set this or HARNESS_API_TOKEN before exposing HTTP routes.
# api_token = "change-me"
# Local-dev escape hatch for tokenless HTTP operation:
# allow_unauthenticated = true

[agents]
default_agent = "auto"
# complexity_preferred_agents = ["codex", "claude"]
sandbox_mode = "danger-full-access"
# Claude enforces Standard tools. Set "full" only for an explicit unrestricted opt-up.
capability_profile = "standard"

[isolation]
default_tier = "container"
# Exact hosts only. Scoped mode with an empty list denies agent networking.
# Linux allowlisted tasks require the container tier; macOS also supports host.
network_allowlist = ["github.com", "api.github.com", "api.openai.com", "api.anthropic.com"]

[agents.claude]
cli_path = "claude"
default_model = "sonnet"

[agents.codex]
cli_path = "codex"

[agents.anthropic_api]
base_url = "https://api.anthropic.com"
default_model = "claude-sonnet-4-20250514"
max_tokens = 4096

[agents.review]
enabled = true
reviewer_agent = "codex"   # local review agent
max_rounds = 3
review_bot_auto_trigger = false

[gc]
max_drafts_per_run = 5
budget_per_signal_usd = 0.50
total_budget_usd = 5.0
draft_ttl_hours = 72

[observe]
log_retention_max_files = 30
log_retention_days = 90

[otel]
environment = "production"
exporter = "otlp-http"
# endpoint = "http://127.0.0.1:4318"

With default_agent = "auto", Claude is the first registered CLI agent. Start Harness with ANTHROPIC_API_KEY set when using the container tier. Harness forwards that provider credential to the Claude container by environment variable name; the value is kept out of Docker arguments. Other ambient operator secrets remain filtered.

HTTP API authentication now fails closed by default. Starting harness serve without server.api_token or HARNESS_API_TOKEN exits with an actionable configuration error. For intentional tokenless local development, set server.allow_unauthenticated = true; if both a token and the opt-in are set, the token wins and bearer authentication stays enforced.

Multi-Project Configuration

Register multiple projects in the config file. Each project gets its own worktree isolation, concurrency limits, and agent overrides.

[[projects]]
name = "harness"
root = "/path/to/harness"
default = true              # default project for API calls without project field
max_concurrent = 2          # max parallel tasks for this project

[[projects]]
name = "litellm-rs"
root = "/path/to/litellm-rs"
max_concurrent = 2
# default_agent = "auto"    # optional override; or set a registered agent name

[[projects]]
name = "vibeguard"
root = "/path/to/vibeguard"
max_concurrent = 1

CLI --project name=path flags merge with config entries (CLI overrides on conflict).

Per-Project Overrides

Each project can have a .harness/config.toml in its root to override server defaults:

# /path/to/project/.harness/config.toml
[git]
base_branch = "develop"
remote = "upstream"
branch_prefix = "fix/"

[validation]
pre_commit = ["cargo fmt --all -- --check", "cargo check"]
timeout_secs = 120

[agent]
default = "auto"            # or set a registered agent name

[review]
enabled = true

[concurrency]
max_concurrent_tasks = 3
max_turns = 20

HTTP REST API

Except for /health, the examples below assume HARNESS_API_TOKEN is exported in the client shell and send it as a bearer token.

Workflow Runtime Submissions

# Submit work by prompt
curl -X POST http://127.0.0.1:9800/api/workflows/runtime/submissions \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add input validation to the API handler",
    "project": "/path/to/project"
  }'

# Submit work by GitHub issue number
curl -X POST http://127.0.0.1:9800/api/workflows/runtime/submissions \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "/path/to/project",
    "issue": 42,
    "prompt": "fix: handle edge case in parser"
  }'

# Submit an issue but bypass triage/plan and go straight to implementation
curl -X POST http://127.0.0.1:9800/api/workflows/runtime/submissions \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "/path/to/project",
    "issue": 42,
    "skip_triage": true
  }'

# Submit a PR for review/fix
curl -X POST http://127.0.0.1:9800/api/workflows/runtime/submissions \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "/path/to/project",
    "pr": 100
  }'

# Submit multiple issues (one durable submission per request)
for issue in 10 11 12; do
  curl -X POST http://127.0.0.1:9800/api/workflows/runtime/submissions \
    -H "Authorization: Bearer ${HARNESS_API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{\"project\":\"/path/to/project\",\"issue\":$issue}"
done

# Get submission status
curl http://127.0.0.1:9800/api/workflows/runtime/submissions/{submission_id} \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}"

# List submissions
curl http://127.0.0.1:9800/api/workflows/runtime/submissions \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}"

# Stream submission output (SSE)
curl http://127.0.0.1:9800/api/workflows/runtime/submissions/{submission_id}/stream \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}"

Project Management

# List registered projects
curl http://127.0.0.1:9800/projects \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}"

# Register a new project at runtime
curl -X POST http://127.0.0.1:9800/projects \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-project",
    "root": "/path/to/project",
    "max_concurrent": 2
  }'

# Remove a project
curl -X DELETE http://127.0.0.1:9800/projects/my-project \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}"

Dashboard

# Get aggregated status across all projects
curl http://127.0.0.1:9800/api/dashboard \
  -H "Authorization: Bearer ${HARNESS_API_TOKEN}"

# Response:
# {
#   "global": { "running": 3, "queued": 1, "done": 42, "failed": 2, "grade": "A" },
#   "projects": [
#     { "id": "harness", "root": "...", "tasks": { "running": 1, "queued": 0 } },
#     { "id": "litellm-rs", "root": "...", "tasks": { "running": 2, "queued": 1 } }
#   ]
# }

Health

curl http://127.0.0.1:9800/health

The response includes a runtime_logs block with the logging state, retention window, max-files cap, and a redacted logs/<filename> hint instead of the full absolute path.

Server Startup

harness serve can be started directly from a normal terminal. When product behavior needs live verification from a Codex or Claude agent session, launch the server with a sanitized environment so spawned agents do not inherit wrapper variables from the parent process. Harness strips Claude-prefixed variables before spawning child agents; Codex-prefixed variables are not stripped by the adapter spawn path, so use scripts/start-harness-codex-safe.sh or an equivalent sanitized launcher when starting from a Codex-owned session. For long-running manual dogfood sessions, a standalone terminal is still useful because the operator owns the process lifetime directly.

# Single project (backward compatible)
./start-server.sh

# Multi-project via config file (recommended)
./target/release/harness --config config/default.toml serve --transport http --port 9800

# Multi-project via CLI flags
./target/release/harness serve --transport http --port 9800 \
  --project harness=/path/to/harness \
  --project litellm=/path/to/litellm

# With GitHub token for auto-review
GITHUB_TOKEN=ghp_xxx ./target/release/harness --config config/default.toml serve --transport http --port 9800

Before using direct ./target/release/harness ... serve commands, run scripts/doctor.sh --config <path> or confirm the same prerequisites manually. The direct binary commands do not start local Postgres or build the release binary for you.

Workflow Runtime Execution Flow

POST /api/workflows/runtime/submissions → persist workflow + implementation command
    → runtime dispatcher creates a job → worker acquires the project queue permit
    → create git worktree → agent executes in isolation
    → validate and review → persist terminal workflow evidence

Each implementation runs in an isolated git worktree. The workflow runtime is the scheduling and lifecycle authority.

Workspace Crates

Crate	Purpose
harness-core	Shared domain types, config, prompts, agent/interceptor traits
harness-protocol	JSON-RPC method definitions, envelopes, notifications, codecs
harness-server	App Server runtime (HTTP + stdio + WebSocket), routing, handlers, and workflow-runtime integration
harness-agents	Agent adapters (Claude CLI, Codex CLI, Anthropic API) and registry
harness-gc	Signal detection and draft remediation generation/adoption
harness-rules	Rule loading/parsing, Starlark execution policy engine
harness-skills	Skill discovery, deduplication, search, and persistence
harness-exec	ExecPlan model plus Markdown serialization/deserialization
harness-observe	Event storage, quality grading, health/stat aggregation, OTLP export
harness-cli	harness binary with exec/gc/rule/skill/plan commands; serve/reconcile are behind the default server feature

JSON-RPC API

Harness exposes methods over JSON-RPC 2.0 (stdio, HTTP, or WebSocket):

Category	Methods
Lifecycle	initialize, initialized
GC	gc/run, gc/status, gc/drafts, gc/adopt, gc/reject
Skills	skill/create, skill/list, skill/get, skill/delete, skill/governance/view, skill/governance/history, skill/stale
Rules	rule/load, rule/check, rule/fix, exec_policy/check
ExecPlan	exec_plan/init, exec_plan/update, exec_plan/status
Observability	event/log, event/query, metrics/collect, metrics/query
Context	context/preview
Classification	task/classify, learn/rules, learn/skills
Health	health/check, stats/query, agent/list
VibeGuard	preflight, cross_review

Contributing

See CONTRIBUTING.md for development setup and PR guidelines.

Security

See SECURITY.md for vulnerability reporting.

The Agent Infra Stack

This project is one layer of an open-source stack for running coding agents (Claude Code, Codex) as serious infrastructure. Each piece works independently; together they close the loop:

harness is the Orchestrate layer — where skills, rules, memory, and models come together into long-running agent runs.

Layer	Project	What it does
Extend	claude-skill-registry	Discover and search community Claude Code skills
Extend	spellbook	Cross-runtime skills for Claude Code, Codex, and multi-agent workflows
Trust	argus	Static install-time scanner for supply-chain attacks (npm / PyPI / crates.io)
Trust	vibeguard	Rules, hooks, and guards against hallucinated or unverified agent changes
Remember	remem	Local-first persistent memory for Claude Code and Codex sessions
Orchestrate	harness ◀ you are here	Rust agent orchestration platform — rules, skills, GC, observability
Route	litellm-rs	High-performance Rust AI gateway — 100+ LLM APIs via OpenAI format
Keep	keepline	Session command center — monitor, recover, never lose agent work

---

License

Licensed under the MIT License.