Installation

Fabric Harness ships as a set of npm packages under the @fabric-harness/* scope. The CLI installs a fabric-harness (alias fh) binary; the SDK is added per-workspace.

Prerequisites

• Node.js 20.18+ for the core SDK, CLI, and Node runtime
• Node.js 22 LTS recommended for new projects
• Node.js 22+ required for @fabric-harness/databricks
• npm 10+, pnpm 10+, or yarn 4+
• (optional) Docker for the Docker sandbox
• (optional) Temporal (local dev server) for the Temporal worker target
• An LLM provider API key (e.g. OPENAI_API_KEY) when you want real model calls.

Some optional Node APIs have narrower requirements: the built-in SQLite stores need Node 22.5 or newer, and native client WebSocket support needs Node 22 or a polyfill. See release and documentation status for the package-by-package contract.

1. Install the CLI

For a new project, run the published CLI directly and let the scaffold install a compatible local CLI and SDK together:

npx --yes @fabric-harness/cli@latest init my-agents
cd my-agents
npm install
npx fh --version

Use a global CLI only when you want fh available outside a project:

npm install -g @fabric-harness/cli

pnpm add -g @fabric-harness/cli

yarn global add @fabric-harness/cli

Inside a project, prefer npx fh (or an npm script). It resolves the version pinned by that project and prevents a global CLI update from getting ahead of its SDK and target packages.

2. Bootstrap a workspace manually

A Fabric Harness workspace is any directory with a .fabricharness/ folder.

mkdir my-agents
cd my-agents
npm init -y
mkdir -p .fabricharness/jobs

3. Add the SDK

The bare @fabric-harness/sdk is enough for most agents. Add the deploy-target package only if you need it.

npm install @fabric-harness/sdk

npm install @fabric-harness/sdk @fabric-harness/cloudflare

npm install @fabric-harness/sdk @fabric-harness/temporal

npm install @fabric-harness/sdk @fabric-harness/azure

Strict mode (@fabric-harness/sdk/strict) is a sub-path export of the same package — no separate install needed.

All published packages

4. Verify

Run the doctor command from your workspace:

npx fh doctor --tools

To verify a real model end-to-end:

echo 'OPENAI_API_KEY=sk-...' > .env.local
npx fh doctor --live --model openai/gpt-5.5

5. Write your first agent

Persistent agents are ordinary synchronous functions. Hooks compose the harness; the returned string is the instruction rendered for the current interaction:

import { createAgent, useModel, useSandbox } from '@fabric-harness/sdk';

function Assistant() {
  useModel('openai/gpt-5.5');
  useSandbox('virtual');
  return 'Answer clearly, verify important claims, and keep the conversation moving.';
}

export default createAgent(Assistant, {
  durability: { maxAttempts: 5, timeoutMs: 60 * 60_000 },
});

npx fh agents
npx fh describe assistant
npx fh run assistant --id first-conversation --new --prompt "What is Temporal?"
npx fh run assistant --id first-conversation --prompt "Why would I use it?"

The second message addresses the same persistent instance, so it continues the conversation. If the configured model responds, you're ready for your first agent.

Updating

npm update -g @fabric-harness/cli                # CLI
npm update @fabric-harness/sdk                   # SDK + add-ons in your workspace

The runtime reliability update is a coordinated portable-runtime release: @fabric-harness/sdk@6.1.0, @fabric-harness/node@6.1.0, @fabric-harness/cloudflare@2.3.0, and @fabric-harness/cli@6.6.1. CLI 6.6.1 generates Databricks projects on the independently versioned @fabric-harness/databricks@^7.0.1 line. Upgrading the portable runtime does not change Databricks workload source, deployment configuration, or its optional peer range.

Releases follow semver, and the npm registry exposes each package's current version and release history. See release and documentation status for the current package matrix and migration links.