Files
openworker/harness
..

OpenWorker Harness SDK

Build your app. OpenWorker handles the agents.

Build and automate complex workflows with agents that use tools, delegate work and collaborate. Create an autonomous coding agent that implements and verifies changes, a support agent that investigates issues and takes action, or a team of agents that coordinates work across your systems. You own the product experience and decide what agents can do; OpenWorker handles the agent loop, model calls, approvals and durable sessions.

Get started · Documentation · SDK reference · Example apps

Under active development. Please try the SDK and open issues for bugs and feature requests. Please hold off on SDK pull requests while the API is evolving.

How it fits into your app

Your app owns the UI, authentication and user/session ownership. It chooses the models, tools and policies. One Rust engine powers both SDKs: TypeScript manages it as a child process; Rust can embed it in-process. Browser code calls your application server or desktop IPC.

OpenWorker architecture: your application uses the TypeScript or Rust SDK to control one Rust harness, which connects to cloud/local models and app-owned or OpenShell-isolated tools.

OpenShell isolates configured shell/file execution while the agent loop remains in the trusted harness. Application callbacks still run with your application’s privileges. See execution boundaries.

The existing OpenWorker Desktop App uses its separate Python engine. This SDK provides the Rust engine for applications you build.

Build with your coding agent

Install the builder skill in your app project:

npx @openworkerai/openworker-harness-builder --agent claude --project .

Use --agent codex for Codex, or replace --project . with --global for all your projects. Open a new coding-agent session and give it a concrete task:

Use the openworker-harness-builder skill to build a local file-organizing app. Start with ten sample text files in a new demo directory. Restrict its file tools to that directory, ask me before creating subdirectories or moving files, and show tool activity as the agent works. Run the tests and explain how to launch it.

The skill supplies SDK instructions and runnable examples; you do not need to clone this repository. See the skill guide for updates, replacement backups and the tested SDK version.

Build your first agent by writing code yourself

We recommend building with a coding agent and the builder skill. The steps below serve as a quick reference, showing how little code it takes to start the harness in your app, create an agent and run a conversation.

Install the SDK:

npm install @openworkerai/harness-sdk

1. Start the harness and connect a model

Your app starts the harness once and supplies its model credentials. This text-only example uses OpenAI and does not need a sandbox.

const harness = await Harness.start({
  stateDir: resolve('.openworker-state'), sandbox: 'off',
});
await harness.setModelProvider({
  name: 'OpenAI', api: 'responses',
  baseUrl: process.env.OPENWORKER_MODEL_URL ?? 'https://api.openai.com/v1',
  credentials: { apiKeyEnv: 'OPENAI_API_KEY', storage: 'memory' },
});

2. Define the agent

Give the agent instructions and select its model. Start without tools; add your application's tools when it needs to take actions.

const agent = harness.createAgent({
  name: 'first-agent-v1', instructions: 'Give concise, helpful answers.',
  defaultModel: { provider: 'OpenAI', name: model },
  tools: [], planning: false, memory: false, scheduling: false,
});

3. Start a conversation

Create a session, send a request and display the answer. Reuse the session for follow-up messages.

const session = await agent.newSession();
const result = await session.run('Suggest three names for a file-organizing app.');
if (result.status !== 'completed') throw new Error(`Run ended: ${result.status}`);
console.log(result.finalOutput);
Complete runnable example and setup

Save as agent.mjs. In a private env file outside your project, set OPENAI_API_KEY to your API key and OPENWORKER_MODEL to an exact model ID available to your account. The complete example includes imports and shuts down the harness even if a request fails.

import { resolve } from 'node:path';
import { Harness } from '@openworkerai/harness-sdk';

const model = process.env.OPENWORKER_MODEL;
if (!model) throw new Error('Set OPENWORKER_MODEL');
const harness = await Harness.start({
  stateDir: resolve('.openworker-state'), sandbox: 'off',
});
try {
  await harness.setModelProvider({
    name: 'OpenAI', api: 'responses',
    baseUrl: process.env.OPENWORKER_MODEL_URL ?? 'https://api.openai.com/v1',
    credentials: { apiKeyEnv: 'OPENAI_API_KEY', storage: 'memory' },
  });
  const agent = harness.createAgent({
    name: 'first-agent-v1', instructions: 'Give concise, helpful answers.',
    defaultModel: { provider: 'OpenAI', name: model },
    tools: [], planning: false, memory: false, scheduling: false,
  });
  const session = await agent.newSession();
  const result = await session.run('Suggest three names for a file-organizing app.');
  if (result.status !== 'completed') throw new Error(`Run ended: ${result.status}`);
  console.log(result.finalOutput);
} finally {
  await harness.shutdown();
}
node --env-file=/path/to/private.env agent.mjs

OPENWORKER_MODEL_URL optionally selects another Responses-compatible endpoint. The SDK runs in your Node process, Electron main process or application server; npm includes the matching Rust runtime. See the TypeScript quickstart for runtime requirements and lifecycle details.

For other providers, see models and credentials. For a native app, follow the Rust quickstart.

When adding tools, choose their execution boundary: application callbacks retain your app’s privileges, and a workspace path alone does not confine filesystem access. The file-organizer example demonstrates scoped tools and human approvals.

Choose an example app

Build Example and source What you’ll learn
Local utility File organizer · Source Custom tools, directory restrictions, streaming and per-operation approvals.
Desktop app Code Atlas walkthrough · Source · Setup Select a code directory and stream an explanation in an Electron UI.
Web app PDF Notes walkthrough · Source · Setup Attach a PDF and ask follow-up questions in its own session.
Edge inspection app InspectionBuddy · Source Assess part photos, record inspector decisions and connect a workstation to an edge agent service. Includes a cluster-free local mode.
Game builder Arcade Studio · Source Build and preview games, approve versions and return to a saved library.

Code Atlas and PDF Notes share examples/quickstart/; they are two complete TypeScript apps. The file organizer is bundled with the skill. The quickstart examples install the published npm SDK and its native runtime. Follow each example README for configuration.

What the SDK handles for you

Your application needs… OpenWorker provides
An agent that gets work done The model/tool loop, streaming, cancellation and context compaction.
Conversations that survive restarts Durable sessions and explicit recovery without blindly replaying uncertain actions.
People in control Human approvals, session grants and optional LLM-assisted review. Approvals
Content and execution controls Guardrails and hooks, plus OpenShell isolation for configured tools. Guardrails · OpenShell
Agents that delegate Standalone sub-agents and teams with durable messages and boards. Sessions and teams
A choice of models Cloud and local providers with application-owned credentials. Models
Visibility into each run Opt-in turn traces, token usage and telemetry export to tools such as Langfuse. Observability

Deployment and observability

Start inside your desktop app, Node process or application container. A separate agent service is optional. Use it when you need API/worker separation, shared PostgreSQL storage and separately managed execution environments. Local apps can use SQLite.

Observability is optional for lightweight applications. Cloud deployment paths are experimental references; qualify your configuration in the target environment before production use.

Documentation

Next step Guide
Add custom tools or MCP servers Tools and MCP
Stream responses and handle approval cards Streaming and approval loop
Accept images, PDFs and text files Attachments
Configure safety and audit controls Alignment · Compliance
Check versions or diagnose a problem Compatibility · Troubleshooting

For developers and coding agents

Use the TypeScript or Rust package README for the integration contract. The installed builder skill records its tested SDK pin in references/installation.json.

  • Preserve immutable agent identities; changing instructions, tools or approvals requires a new name.
  • Keep credentials and durable state outside model-readable files.
  • Use real user decisions for human approval requests. Stopping observation does not cancel execution.
  • Reconcile unknown tool outcomes before retrying.
  • Prefer public SDK/service interfaces over runtime tables or private transport methods.
Versions and native runtime compatibility

npm installs the matching platform runtime package automatically; keep optional dependencies enabled. Source manifests and published package versions can differ. Follow the release and compatibility guide when pinning or upgrading, rather than inferring registry availability from a source version string.

Rust applications currently use a pinned source checkout. See the Rust quickstart; npm publication does not imply Cargo registry publication.

Need to change the engine or register native tools? See the native host guide, Tools SDK and workspace CI.

Build and test this checkout

Use the pinned toolchain, Node.js and your platform's native prerequisites. See Windows build notes when applicable.

cd harness
cargo build --release --locked -p openworker-sdk --bin openworker-harness
npm --prefix typescript-sdk ci
npm --prefix typescript-sdk run build

The host is target/release/openworker-harness (.exe on Windows). Build a custom SDK/helper pair from the same revision; npm consumers normally use the packaged runtime.

cargo fmt --all -- --check
cargo test --locked -p openworker-sdk --features test-support --test provider_auth
npm --prefix typescript-sdk test

OpenShell, PostgreSQL and live-provider checks require their documented setup. The documentation site is built from repository Markdown.

MIT license.