# nan-harness — docs

Documentation for running supported coding agents with NaN through nan-harness.

- HTML: https://nan-harness.davidlms.com/docs.html
- Markdown: https://nan-harness.davidlms.com/docs.md

Run the coding agents you already use with [NaN](https://nan.builders/) through nan-harness. Use `nanh <harness>` for everyday launches and `nanh config <harness>` only for advanced native setup. `nanh` is the shorter alias for `nan-harness`.

## INSTALL

Run this on macOS or Linux:

```
curl --proto '=https' --tlsv1.2 -m 30 -fsSL https://github.com/DavidLMS/nan-harness/releases/latest/download/install.sh | sh
```

On Windows, in PowerShell:

```
irm https://github.com/DavidLMS/nan-harness/releases/latest/download/install.ps1 | iex
```

If prompted, open a new terminal. Then verify the installation:

```
nanh --version
```

The installer provides both `nan-harness` and `nanh`. Release builds are available for macOS, Linux, and Windows. To build from source, see the [repository](https://github.com/DavidLMS/nan-harness).

## FIRST RUN

Go to your project and launch the agent you already use:

```
nanh claude
```

If `NAN_API_KEY` is not set, nan-harness asks for your NaN API key the first time it needs one. It verifies and saves the key.

After that, use the agent as usual. To choose a model at launch, use `--model`. If supported, you can also use the agent's native model picker:

```
nanh codex --model qwen3.6
nanh opencode --model deepseek-v4-flash
```

Pass arguments to the agent after `--`; nan-harness forwards them unchanged:

```
nanh codex --model qwen3.6 -- --full-auto
nanh claude -- --resume
```

### Your key

> If you already have `NAN_API_KEY` in your environment, this section does not apply to you. That key wins over any other: nan-harness will not ask you for one, saves nothing to disk, and there is no need to log in.

If you do not, nan-harness keeps it where your system keeps passwords: Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. If none of them is available it uses a private file and warns you.

| Command | What it is for |
| --- | --- |
| nanh auth login | Enter a key, or replace the one you have. |
| nanh auth status | See which key is in use and where it is stored. |
| nanh auth logout | Delete the saved key. |

The environment variable is useful on servers and in CI. `nanh auth status` shows which credential is active:

```
export NAN_API_KEY="<your-NaN-api-key>"
```

> Keep your key private. The environment variable is never copied into a harness configuration.

## HARNESSES

`nanh <harness>` is the recommended workflow for every supported harness. nan-harness checks the installed version, reads the current NaN catalog, prepares any required bridge and supervises the process without changing persistent provider settings. `nanh config <harness>` is an advanced option for harnesses that support direct native configuration.

| Recommended command | Harness | Native setup |
| --- | --- | --- |
| nanh aider | [Aider](https://aider.chat/) | optional |
| nanh cline | [Cline](https://cline.bot/) | optional |
| nanh goose | [Goose](https://github.com/block/goose) | optional |
| nanh claude | [Claude Code](https://www.anthropic.com/claude-code) | not available |
| nanh codex | [Codex](https://openai.com/codex/) | not available |
| nanh opencode | [OpenCode](https://opencode.ai/) | optional |
| nanh qwen | [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/users/overview) | optional |
| nanh pi | [Pi](https://pi.dev/) | optional |
| nanh kimi | [Kimi Code](https://www.kimi.com/code) | optional |
| nanh openclaw | [OpenClaw](https://openclaw.ai/) | optional |
| nanh hermes | [Hermes Agent](https://hermes-agent.nousresearch.com/) | optional |
| nanh omp | [Oh My Pi](https://omp.sh/) | optional |
| nanh prime-agent | [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) | optional |
| nanh dsh | [DeepSeek Harness](https://deepseek.com/harness/en/) | optional |
| nanh fx | [fx](https://fx.sh/) | not available |

### Recommended: run with nan-harness

For everyday use, run `nanh <harness>`. It checks the installed version, discovers your current NaN models, uses your current credential source, prepares any required bridge, and supervises the process. If the harness is missing, nan-harness can offer to install it.

```
nanh opencode
```

### Advanced: native setup

Use `nanh config <harness>` only when another tool or integration needs to start a supported harness with its usual executable. Native setup writes persistent provider settings. The later launch runs directly through the harness, so nan-harness no longer manages that process. This command only configures the harness; start it afterwards with its usual executable:

```
nanh config opencode
opencode
```

Claude Code, Codex and fx need nan-harness running because their NaN connection depends on a local bridge or gateway. They cannot be prepared for standalone use with `nanh config`.

Native setup uses the API key saved by `nanh auth login`; an environment-only key is never copied into another application. Use `--status` to inspect it and `--refresh` after changing your saved key or model catalog. `--remove` removes what nan-harness added and restores previous settings when it is safe to do so.

## DESKTOP APPS (EXPERIMENTAL)

These integrations are experimental. All five apps have been tested on macOS. Other platform combinations are covered by automated compatibility tests.

| Command | App | Available on |
| --- | --- | --- |
| nanh zed | [Zed](https://zed.dev/) | macOS, Windows, Linux |
| nanh chatgpt-desktop | [ChatGPT](https://openai.com/chatgpt/desktop/) | macOS, Windows, Linux (preview) |
| nanh claude-desktop | [Claude](https://claude.ai/download) | macOS, Windows, Linux (beta) |
| nanh hermes-desktop | [Hermes](https://hermes-agent.nousresearch.com/) | macOS, Windows, Linux |
| nanh pen | [Pen](https://www.pen.dev/) | macOS, Windows, Linux |

### What happens when you launch one

nan-harness prepares a temporary NaN connection, launches the app, and cleans up when it closes. It does not replace the app or log you out; your login, history, and settings stay intact.

ChatGPT and Hermes use a separate profile. Claude, Pen, and Zed restore their previous configuration when they close. Pen and Zed receive all text models available to your NaN account through a private local gateway, which also provides the final token-usage summary.

### If a launch is interrupted

Close the app and run the same command again with `--restore`. nan-harness restores the state recorded for the interrupted launch.

### Run Hermes or Pen directly

Hermes Desktop and Pen can also be configured for direct use. After that, open the app normally; nan-harness is no longer involved. Usage summaries work only when you launch through `nanh`. Pen must be fully restarted to reload a changed model catalog:

```
nanh config hermes-desktop
hermes desktop
nanh config pen
open Pen normally
```

> If you are interested, try them and tell us. Your experience as a user — what works, what breaks, what you miss — is the best way to help make these integrations solid.

## SEARCH WITH NAN

Many coding agents can search the web. When nan-harness launches one, it checks whether the agent already has a recognized search provider — in the agent, the project or its local search configuration. Only when it does not find one does it add NaN web search as a fallback. Your existing search settings are never touched.

The agent sees it as a normal web-search tool, so you just ask it: "search the web for the latest Rust release notes", "look up how other people fixed this error", or "find the official docs for that library". The request goes through your NaN account like any other model call.

### Override the selection

| Flag | What it does |
| --- | --- |
| (default) | Automatic: adds NaN search only if no other recognized provider is configured. |
| --no-search | Never adds NaN web search for this launch, even without another provider. |
| --force-search | Adds NaN web search even when another provider exists. |

```
nanh claude --no-search
nanh cline --force-search
```

For Pi and Prime Agent, the check also inspects the runtime tool inventory after installed package extensions load. Any package exposing a tool named `web_search` suppresses the NaN fallback on its own; `--force-search` gives the NaN tool precedence instead.

### In native setup

`nanh config <harness>` applies the same policy. A chosen `--force-search` or `--no-search` is stored in the configuration receipt and kept on later `--refresh` runs unless you pass a new flag. `nanh config --status` shows the stored policy and whether the NaN fallback is active.

For Pi, Oh My Pi and Prime Agent, native setup installs a runtime-aware extension rather than a search MCP entry; refreshing an older configuration migrates it automatically and preserves unrelated MCP servers. Aider supports native model configuration but not the NaN web search fallback.

## OPTIONS

### Recommended launch options

| Option | What it does |
| --- | --- |
| --model <id> | Which model to use this time. |
| --allow-untested | Allows a command-line harness version that cannot be read, or a desktop app version newer than the last live-tested version. |
| --allow-unsupported | Runs a version below the supported minimum. |

### Advanced native setup commands

| Command | What it does |
| --- | --- |
| nanh config <harness> | Writes a reversible native NaN configuration without launching the harness. |
| nanh config <harness> --status | Checks whether its managed configuration is current. |
| nanh config <harness> --refresh | Updates the copied key, model catalog and managed defaults. |
| nanh config <harness> --remove | Removes the managed configuration and restores safe previous values. |

### Other commands

| Command | What it does |
| --- | --- |
| nanh doctor | Checks everything and tells you how it looks. |
| nanh doctor <harness> | Checks one harness in detail. |
| nanh auth login | Saves your NaN key. |
| nanh auth status | Tells you which key is in use. |
| nanh auth logout | Deletes the saved key and lets you remove configurations that contain a copy. |
| nanh config --status | Shows every native configuration managed by nan-harness. |
| nanh config --refresh-all | Refreshes every managed native configuration. |
| nanh config --remove-all | Removes every managed native configuration. |
| nanh update | Updates nan-harness to the latest version. |
| nanh telemetry on\|off | Turns anonymous telemetry on or off. |
| nanh uninstall | Removes nan-harness and everything it left behind. |
| nanh --help | The full list, in your terminal. |

## HELP AND PRIVACY

### Troubleshooting

Run `nanh doctor` to check connectivity, model availability, installed harnesses, and stale versions.

```
nanh doctor
```

That report is safe to share: it excludes keys, paths, prompts, and model output. The single-harness report includes the executable path, so review it before sharing.

```
nanh doctor claude
```

### Version warnings

Each release of nan-harness is tested against specific versions of each harness. If yours is newer than the last tested version, nan-harness warns you and continues. Older versions below the minimum require `--allow-unsupported`; versions whose number cannot be read require `--allow-untested`.

### Telemetry

Off unless you turn it on. If enabled, nan-harness can send sanitized CLI and bridge error reports plus a minimal invocation event with a random installation identifier, its version, the harness, operation, transport, OS family, architecture, and target environment. It never sends prompts, model output, arguments, paths, credentials, usernames, or hostnames. A model-specific diagnostic may include the NaN model ID. As with any HTTPS request, the receiving infrastructure can observe ordinary network metadata.

```
nanh telemetry on
nanh telemetry off
```

It helps us see which harnesses need attention. Turning it off stops usage events and automatic error delivery. An interactive error may still offer a one-time anonymous report.

### Uninstalling

It asks for confirmation, undoes every configuration it left in your agents, deletes your saved key and removes itself. If you changed one of those configurations by hand, it stops instead of overwriting your work.

```
nanh uninstall
```