Skip to content

Open Agent Harness

A Headless Agent Engine

Define agent runtimes in Markdown, switch by scenario, run many workspaces in parallel. You build the product UI. This is the backend engine.

Get Started Architecture

What It Is

Open Agent Harness is a deployable Agent Engine. It runs Agent Runtime units and extends them with Agent Spec. It manages workspace lifecycles, agent execution loops, tool invocations, and state persistence without shipping a product UI.

The shipped web console and terminal TUI are debug surfaces rather than product UI. Use the web console for browser-based trace and storage inspection, or the TUI when you are already working in a shell and want to select a workspace, enter a session, and watch streaming output.

Core Capabilities

  • Parallel workspaces — PostgreSQL for persistence, Redis for queues and coordination. Many workspaces run concurrently.
  • Declarative runtime structure — Define agent/runtime behavior in Markdown and YAML. Hot-reloaded.
  • Composable capabilities — agent / skill / action / tool / hook / context are configured independently per workspace.
  • One workspace model — the same directory structure supports conversation, tools, and execution.
  • REST + SSE API — Everything exposed under /api/v1. Frontend-agnostic.
  • Debug TUI — Workspace and session debugging in the terminal over the same API / SSE surfaces.
  • Flexible deployment — Use oah-api with an embedded worker for the smallest deployment, or split into oah-api + oah-controller + oah-sandbox.

Quick Start

pnpm install                                        # Install dependencies
mkdir -p /absolute/path/to/oah-deploy-root
cp -R ./template/deploy-root/. /absolute/path/to/oah-deploy-root
export OAH_DEPLOY_ROOT=/absolute/path/to/oah-deploy-root
pnpm local:up                                       # Start PostgreSQL + Redis + MinIO + oah-api + oah-controller + oah-sandbox, then auto-sync once
pnpm dev:web                                        # Start debug console
pnpm dev:cli -- --base-url http://127.0.0.1:8787 tui # Start terminal TUI

After startup:

Full guide

Where to Go

  • Quick Start

    Install, launch, verify — up and running in 5 minutes

    Start

  • Architecture

    Layered design, core modules, request flow

    View

  • Terminology

    Shared boundaries for Engine, Runtime, and Spec

    View

  • Workspace Config

    Agents, models, skills, actions, hooks

    Configure

  • Deploy and Run

    Local dev, split deployment, single workspace mode

    Deploy

  • Debug CLI / TUI

    Debug workspaces, sessions, catalogs, and streaming output from the terminal

    View