OpenWorker Harness SDK
Build your app. OpenWorker handles the agents.
Give your desktop or web app agents that can use tools, work together and keep conversations across restarts. Keep your interface and product workflow while the harness manages the agent loop, model calls, approvals and session storage.
Get started · Documentation · Builder Skill · Examples
One Rust engine powers both SDKs. TypeScript runs it as a managed child process; Rust can embed it in-process. The current OpenWorker Desktop application uses its separate Python engine.
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.
Choose your starting point
| You are building… | Start here |
|---|---|
| A Windows or Mac desktop app | Desktop walkthrough · Electron/Tauri starters |
| A web app with its own backend | Web walkthrough |
| A local script or command-line utility | Runnable file-organizer agent |
| A Rust application | Rust SDK quickstart |
| A shared agent service | Deployment choices · Local service setup |
TypeScript: install from npm
npm install --save-exact @openworkerai/harness-sdk@0.1.0-beta.4
npm includes the matching native runtime automatically. No Rust compiler or Python installation is needed. This client documentation release uses native runtime 0.1.0-beta.3. Run the SDK in Node.js 20+, Electron main or your server; the browser talks to your app's API. See the TypeScript quickstart.
Rust: embed from a pinned checkout
Use openworker-sdk from a pinned checkout with the repository's Rust toolchain.
The Rust quickstart includes dependencies and a complete
program. npm availability does not imply Cargo registry publication.
Build with Codex or Claude Code
npx @openworkerai/openworker-harness-builder --agent claude --project .
Use --agent codex for Codex or --global for user-wide installation. Existing
installs ask before replacing and save a backup; scripts can use
--replace-existing. The Skill includes version-matched
instructions and runnable examples without requiring a repository checkout.
What your application gains
| Outcome | What the harness provides |
|---|---|
| Ship your product experience sooner | One agent loop for provider requests, tools, streaming and compaction. |
| Keep conversations across restarts | Durable sessions and explicit recovery, without blindly replaying uncertain actions. |
| Keep people in control | Human approvals, session grants and optional LLM-assisted review. |
| Choose where work happens | App-owned tools or isolated execution through NVIDIA OpenShell. |
| Divide larger tasks | Standalone sub-agents and agent teams with durable messages and boards. |
| Use the model that fits | OpenAI, Anthropic and compatible cloud/local endpoints, with app-owned credentials. |
| Understand what happened | Opt-in turn traces, usage accounting and telemetry export to tools such as Langfuse. |
Your app and the harness
Your app owns the UI, authentication, user/session ownership and product workflow. It chooses the tools, models and policies. The harness enforces its configured controls; an application callback still has the application's privileges.
OpenShell isolates configured shell/file execution while the agent loop stays in the trusted harness. A workspace path alone is not an OS sandbox. See execution boundaries, guardrails and hooks, alignment and compliance.
Try an example
| Example | What it demonstrates |
|---|---|
| File organizer | Custom tools, confined directory operations, activity and per-operation approvals. |
| Code Atlas | A desktop UI that explains a selected code directory. |
| PDF Notes | A web app that accepts a PDF and answers questions about it. |
| Arcade Studio | A desktop application that builds and previews games. |
Deployment and operations
Start in one application process or container. Use the service when you need API/worker separation, durable shared storage and separately managed execution. The service uses PostgreSQL; local apps can use SQLite.
- Local containers and Kubernetes
- AWS, Azure, GCP and private Kubernetes
- Management CLI, management UI and observability
Cloud deployment paths are experimental references. Qualify your configuration in the target environment before using it for production. Read versions and compatibility before upgrading.
For developers and coding agents
Start with the matching package README: TypeScript or
Rust. Use the builder Skill's installation.json to find
its exact SDK pin. Source release manifests and npm client/native versions can
differ; do not infer registry availability from a source version string.
- Preserve immutable agent identities; changing instructions/tools/approvals requires a new name.
- Keep credentials and durable state outside model-readable files.
- Use real user decisions for approvals; observation is independent from execution.
- Reconcile unknown tool outcomes before retrying.
- Prefer public SDK/service interfaces over runtime tables or private transport methods.
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.