Quickstart

Install

npm install nativeharness

Node 22+, and a container engine for the sandbox — podman or docker. Check with npx nativesandbox doctor, or see requirements.

Run a command in a sandbox

import { Harness } from "nativeharness";

const harness = new Harness({ root: "./data" });
const workspace = await harness.workspace({ name: "demo", actor: "user-42" });

await workspace.write("/main.js", "console.log(41 + 1)");
const { result } = await workspace.exec("node main.js && echo built > out.txt");

result.stdout;                         // "42\n"
result.files.changed;                  // ["/out.txt"]
await workspace.readText("/out.txt");  // "built\n"

The file you wrote was hydrated into a fresh sandbox, the command ran there, and the file the command created was synced back. The sandbox is disposable; the workspace is what survives.No model is needed for any of this.

Add a model

import { AnthropicAdapter } from "@nativeharness/adapter-anthropic";

const harness = new Harness({ root: "./data", model: new AnthropicAdapter() });

Reads ANTHROPIC_API_KEY. Four other adapters ship — OpenAI and compatible services, Gemini, Cohere, and local models through Ollama. See models.

Let it work

for await (const event of workspace.chat("read main.js and make it print the date too")) {
  if (event.type === "token")  process.stdout.write(event.payload.text);
  if (event.type === "output") process.stdout.write(event.payload.chunk);
  if (event.type === "done")   console.log("\n", event.payload.status);
}

Tokens stream as the model writes them, commands print as they run, and the files it changed are in the workspace when the turn is done. Every event is persisted before it is emitted, so a client that reconnects can replay exactly what it missed.

Do it for a second user

const other = await harness.workspace({ name: "demo", actor: "user-99" });

A different workspace, a different sandbox, different files. Neither agent can reach the other’s work — see your users.

From the terminal

The same thing without writing any code:

npm install -g @nativeharness/cli

nhar create demo                     # a workspace, with you granted access
nhar exec <id> "npm test"            # a command in its sandbox, streamed
nhar chat <id> -m "fix the failing test"

See the CLI.

How it works

What happens between chat() and the file appearing in your workspace.

Your UI

Rendering the event stream in a browser.

Getting started

How it works

Building your app

CLI

Operations

From the terminal

Next

How it works

Your UI

​From the terminal

​Next

How it works

Your UI

From the terminal

Next