OpenWorker Harness SDK for TypeScript
Build a desktop app, web app or Node.js utility with an agent that can use your tools and keep its conversation across restarts. Your app owns the interface; OpenWorker manages the agent loop.
SDK overview · Desktop guide · Web guide · API declarations
Install
npm install @openworkerai/harness-sdk
Requires Node.js 20+ and ESM. This documentation-only client release uses the unchanged native runtime 0.1.0-beta.3. npm selects the exact platform package; keep optional dependencies enabled. No Rust compiler or Python installation is needed. Run the SDK in Node, Electron's main process or your application server; browser code calls your app's API or IPC.
Run your first agent
Save as agent.mjs. Provide OPENAI_API_KEY and OPENWORKER_MODEL in your process
environment or a private env file. Use an exact model ID available to your account.
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.
This text-only example exposes no tools and explicitly disables sandboxing.
When adding tools, choose their execution boundary deliberately. Node callbacks
retain your app's privileges; workspace alone does not confine filesystem access.
See custom tools and scope.
Build with your coding agent
npx @openworkerai/openworker-harness-builder --agent claude --project .
Use --agent codex for Codex or --global for user-wide installation. Existing
installs prompt before replacement; --replace-existing skips the prompt and
saves a backup. The Skill's installation.json records its tested SDK version.
See the Skill guide and runnable
file-organizer example.
Add the next capability
| You want to… | Start here |
|---|---|
| Add tools and show their arguments | Tools and MCP |
| Stream text and handle approval cards | Streaming and approval loop |
| Change models or refresh credentials | Models and credentials |
| Resume a conversation or delegate work | Sessions and teams |
| Accept images, PDFs and text files | Attachments |
| Isolate tools and inspect content | OpenShell · Guardrails |
| Inspect turns and export traces | Observability |
| Run a shared service | Deployment options |
Integration contract
- Start one harness for the app/service lifecycle; always shut it down on exit.
- Use
createAgentandsetModelProviderfor new apps. Explicit executables, startup agent arrays andsetConnectionare advanced interfaces. - Agent definitions are immutable in durable state. Change the name when changing instructions, tools or approval mode. Identical registration is safe.
- Node resolves
apiKeyEnvand sends the key over private stdio.inheritEnvis unnecessary for this credential path. Memory-only keys must be resupplied after app restart; the SDK does not load env files automatically. - Save
session.reference()and useagent.resumeSession(reference)for recovery. Stopping observation does not cancel work; usesession.cancel()for Stop. - Never automatically retry an action whose outcome is unknown. Reconcile durable state and the external system first.