---
title: The harness library
description: What @venom/harness is, which package to use for your app, how to install it and where each part of the library is documented.
section: harness
order: 0
audience: [builder, agent]
sources: [packages/harness/package.json, packages/harness/src/index.ts, packages/harness/AGENTS.md, docs/build-an-agent-app.md, docs/adr/0002-harness-as-library.md]
features: [harness.build-an-agent-app]
---

`@venom/harness` is the agent harness the venom CLI runs on, published as a library so other programs can run the same coding-agent sessions. It gives you sessions with tools, a permission engine you control, Claude Code compatibility, subagents, context management and a model provider for any OpenAI-compatible server. It has no UI: your program decides what the agent may do and what to show.

Typical apps built on it:

- a CI bot that reviews a diff and fails the build on findings;
- a support or collections back office where an agent reads accounts through your own tools, drafts messages, and every action that touches a customer waits for a human approval in your UI;
- an internal "fix this ticket" service that runs sessions in throwaway workspaces with a fixed policy;
- another agent framework that only wants the policy engine, to vet shell commands an LLM proposes.

## Which package {#packages}

| You want | Use | Runs in |
|---|---|---|
| Sessions inside a Node process, your own tools, direct access to pi's session object | `@venom/harness` | your process |
| Sessions behind HTTP and Server-Sent Events, clients in any language, approvals answered remotely | `@venom/harness-server` (embedded with `createHarnessServer`, or the CLI's `venom serve`) | your process, or the CLI |
| A Python program driving those sessions | `venom-client` | your process, talking to a server |

The HTTP side is documented in the [server API section](/docs/server-api.md) and the generated reference at `/docs/api/harness-server`.

## Install {#install}

The packages are not on a registry. Build them from a venom checkout, then install the tarballs:

```bash
make libs                       # dist/libs/venom-harness-0.1.0.tgz, venom-harness-server-0.1.0.tgz, the venom_client wheel
make libs VERSION=0.2.0-rc.1    # stamp a version
```

```bash
npm install /path/to/venom-harness-0.1.0.tgz
# with the server, install both tarballs in one command (the server depends on the harness at the same version)
npm install /path/to/venom-harness-0.1.0.tgz /path/to/venom-harness-server-0.1.0.tgz
```

Release builds (`make release VERSION=…`) put the same tarballs next to the CLI. Do not `npm install` the `packages/harness` directory of a checkout: npm links it, and the app then runs on the checkout's `node_modules`.

| Requirement | Value |
|---|---|
| Node | 22.19 or newer (`engines`). ES modules; `require()` also works through Node's `require(esm)` |
| TypeScript | `"skipLibCheck": true`. pi's declaration files do not type-check under `module: NodeNext` |
| Runtime dependencies | pi 1.1.0 (`@earendil-works/pi-*`, exact pins), `typebox`, `yaml` |
| Network | Only the model server you configure, MCP servers the user configured, and the web and browser tools when the model calls them (each through the permission gate) |

```json
{ "compilerOptions": { "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, "skipLibCheck": true } }
```

Every type you need is exported from `@venom/harness` and its subpaths, including pi's tool and extension types and typebox's `Type`, so your app does not depend on pi or typebox directly.

## What the library guarantees {#guarantees}

- No global mutable state and no `process.env` writes: several harnesses and sessions in one process are fine.
- No TTY needed. A tool call the policy would "ask" about, with no approver configured, is denied with a reason the model reads; it never hangs.
- Nothing is written under `.claude/` or `~/.claude`.
- A short hard-deny set (secret files, shell rc files, system paths, `rm -rf ~`, piping a download into a shell) applies whatever your rules and approver say.
- What is a breaking change is defined by the "Public API" contract that ships with the package; anything not exported from an entry point is internal.

## Where to start {#map}

| Page | Read it when |
|---|---|
| [Embed the harness](/docs/harness/embedding.md) | You want a first session running in Node, a Next.js route handler or a worker |
| [Sessions, events and cost](/docs/harness/sessions.md) | You need every `HarnessOptions` and `CreateSessionOptions` field, the event stream and saved sessions |
| [Your own tools and approvals](/docs/harness/tools-and-approvals.md) | Your agent needs app-specific tools and your own approval policy |
| [The permission engine](/docs/harness/permissions.md) | You want rules, modes, the sandbox and audit records, with or without a session |
| [Model provider](/docs/harness/providers.md) | You point sessions at a model server, map aliases or handle provider errors |
| [Subagents and model tiers](/docs/harness/subagents.md) | The agent should delegate to cheaper models, in parallel or in worktrees |
| [Build a SaaS on the harness](/docs/harness/saas-recipe.md) | A worked design: a multi-tenant collections back office |
| [`@venom/harness/ws`](/docs/harness/ws.md) | You need a WebSocket server with no dependency, as the browser relay and the voice tests do |

Every entry point of the package, with what it is for, is in [Entry points](/docs/harness/entry-points.md).


## In this section {#in-this-section}

- [Embed the harness](/docs/harness/embedding.md): Run a first venom session from Node, from a Next.js route handler and from a background worker, with state kept where your app wants it.
- [Sessions, events and cost](/docs/harness/sessions.md): Every HarnessOptions and CreateSessionOptions field, the event stream a session emits, saved sessions and how to read a session's cost.
- [Your own tools and approvals](/docs/harness/tools-and-approvals.md): Give the agent app-specific tools with defineTool, decide every permission ask in your own code, and see how the permission engine treats your tools.
- [@venom/harness/ws: a WebSocket server with no dependencies](/docs/harness/ws.md): The server side of RFC 6455 for a node:http server's upgrade event, as used by the browser relay and the voice tests.
- [The permission engine](/docs/harness/permissions.md): Use @venom/harness/permissions to judge tool calls with venom's rules and modes, run commands in the OS sandbox and keep audit records, with or without a session.
- [Model provider](/docs/harness/providers.md): Point harness sessions at any OpenAI-compatible server, map venom's model aliases to real models, and understand the provider's errors and model discovery.
- [Subagents and model tiers](/docs/harness/subagents.md): How the agent delegates work to subagents through the task tool, which built-in agents ship, how model tiers pick cheaper models, and how writers get their own git worktrees.
- [Claude Code compatibility, config and plugins](/docs/harness/claude-code-compat.md): What a harness session reads from a project (CLAUDE.md, .claude/, .mcp.json, venom.yaml, plugins, templates), how trust gates it, and the library APIs behind each.
- [Context, memory and the agent runtime](/docs/harness/context-and-memory.md): How a session keeps its context small (masking, compaction, recall), carries memory between sessions, undoes file changes, and runs its agents as processes you can signal and suspend.
- [Entry points](/docs/harness/entry-points.md): Every import path of @venom/harness, what it is for and whether it loads pi, with the API of the modules that have no page of their own.
- [Build a SaaS on the harness](/docs/harness/saas-recipe.md): A worked design for a multi-tenant app on @venom/harness, using a collections back office as the example: tenancy, tools, human approvals, audit, cost caps and deployment.
