Harness AI 工作流

Prerequisites

- Rust 1.88+ - Bun 1.1+ for release builds that embed the web dashboard. If web/dist is already built, release builds can reuse it. - At least one agent runtime: - codex CLI - claude CLI - Anthropic API key (for direct API adapter)

Build

git clone https://github.com/majiayu000/harness.git
cd harness
cargo build

Database Setup

Harness requires Postgres 14+ (SQLite was removed in v0.x). Configure server.database_url in your TOML config before starting the server — migrations run automatically on first connect.

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

```bash

Quick Start

in your config file (for example `config/default.toml`).

**Option B — docker compose directly:**

in your config file.

**Option C — existing Postgres instance:**

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

**Running tests against a real database:**

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.

Configuration

All settings are declarative TOML. Pass --config <path> or use the defaults in config/default.toml.

```toml [server] transport = "stdio" http_addr = "127.0.0.1:9800" data_dir = "~/.local/share/harness" project_root = "."

[agents] default_agent = "auto"

Multi-Project Configuration

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

```toml [[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).

/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 ```

Multi-project via config file (recommended)

./target/release/harness serve --transport http --port 9800 --config config/default.toml

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.

endpoint = "http://127.0.0.1:4318"

```

HTTP REST API

Multi-project via CLI flags

./target/release/harness serve --transport http --port 9800 \ --project harness=/path/to/harness \ --project litellm=/path/to/litellm

JSON-RPC API

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

Common Workflows

```bash