nhar

npm install -g @nativeharness/cli

Installs nhar, and nativeharness in full. Without installing: npx -p @nativeharness/cli nhar.

nhar and nh are different programs. nhar is this CLI, on your machine, and it can do everything — including delete a workspace. nh is the connector shim: a small command that exists only inside a sandbox, for the model to reach connectors with, and it can do nothing else. You will never type nh yourself, and nothing you install puts it on your PATH.

Workspaces

nhar create [name]        # a workspace, with you granted commit on /
nhar ls                   # every workspace in the root
nhar inspect <id>         # sandbox spec, permissions, files, recent sessions
nhar rm <id>              # delete it and its history

create grants the acting user permission. Without that the workspace would exist and refuse every command, because BashTool checks that the session’s actor is in permissions.

Work

nhar exec <id> "npm test"          # in the workspace's sandbox, streamed; exits with its status
nhar files <id>                    # what the workspace owns
nhar cat <id> /dist/report.txt
nhar put <id> /src/main.js --from ./main.js     # or from stdin

exec hydrates the workspace’s files into a sandbox, runs the command, prints its output as it arrives, syncs the changes back, and prints how many files changed. --timeout <seconds> caps it.

Agent

nhar chat <id>                              # interactive
nhar chat <id> -m "add a test for the parser"   # one turn, then exit
  --model <spec>       anthropic · anthropic/claude-opus-5 · openai/gpt-5 · ollama/<name> · scripted:<file>
  --session <id>       continue an earlier session
  --yes                allow held commands without asking (for CI)

Tokens stream as the model writes; commands print as they run, with output live; a held command asks allow it? [y/N]; a question from the model is asked inline with numbered options. Ctrl+C cancels the turn — durably, recorded with who stopped it — and a second Ctrl+C leaves. With no model configured it exits 2 and lists the environment variables to set.

Portability

nhar export <id> [dest]    # a directory with a checksum; dest defaults to the cwd
nhar import <src>          # into this root, with reconciliation reported

Host

nhar doctor                # root, actor, and whether the sandbox engine answers; non-zero if not

For the engine itself, npx nativesandbox doctor --deep goes further and proves the kernel is holding a memory limit.

Options and environment

Flag	Env
`--root <dir>`	`NH_ROOT`	where workspaces live — default `~/.nativeharness/workspaces`
`--sandbox-root <dir>`	`NH_SANDBOX_ROOT`	where sandbox directories live
`--socket <path>`		the engine socket, overriding auto-detection
`--actor <name>`	`NH_ACTOR`	who is acting — default: your username
`--model <spec>`	`NH_MODEL`	see above
`--json`		machine-readable output where it makes sense

Exit codes


`0`	it worked; for `chat`, the turn completed
the command’s own	`exec` passes it through
`1`	it failed — no engine, no such workspace
`2`	you typed it wrong, or no model is configured
`3` / `4`	`chat`: the turn ended `needs_continuation` with no terminal to answer / `blocked`
`130`	`chat`: cancelled

Getting started

How it works

Building your app

CLI

Operations

Workspaces

Work

Agent

Portability

Host

Options and environment

Exit codes

​Workspaces

​Work

​Agent

​Portability

​Host

​Options and environment

​Exit codes

Workspaces

Work

Agent

Portability

Host

Options and environment

Exit codes