nan-harness

INSTALL

Run this on macOS or Linux:

On Windows, in PowerShell:

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

The installer provides both nan-harness and nanh. Release builds are available for macOS, Linux, and Windows. To build from source, see the repository.

FIRST RUN

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

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:

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

Your key

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.

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

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: 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.

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:

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.

NATIVE MEDIA

Hermes Agent and OpenClaw can route native media features through NaN. nan-harness preserves an existing media provider and adds a NaN provider only when that capability is not already configured.

Use it during a launch

Choose an image model

Use --image-model with Hermes Agent or OpenClaw to choose the default image model. Qwen Image 2.1 is for generation and Flux 2 Klein also supports editing and up to four reference images. The --image and --force-image options use Flux by default.

You can choose a model for one image request in the native image tool without changing the configured default. Ask for Qwen Image 2.1 for generation or Flux 2 Klein for editing. A Qwen request with references returns an error.

Use it in native setup

Pass the same flags to nanh config hermes or nanh config openclaw to write the media providers into the harness configuration. The managed media selection, including the image model, is retained when you refresh that configuration.

PLATFORM NOTES

Some integrations depend on distributions supplied by the upstream harness. nan-harness reports these limits before it searches for an executable or offers installation.

On Windows, you can pass --executable <path> to try a future compatible Prime Agent or fx build. The usual version and launch checks still apply.

DESKTOP APPS (EXPERIMENTAL)

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

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:

SEARCH WITH NAN-HARNESS

nan-harness can give your agent a web search tool backed by SearXNG. It is optional: nothing is installed or contacted until you set up a backend.

Set it up

nan-harness checks that the backend works before saving it. No SearXNG credentials are stored.

Manage it

How your agent uses it

If your agent already has a search provider, nan-harness leaves it alone. If not, it adds its own search tool. Just ask: "search the web for the latest Rust release notes".

Without a backend, the tool replies with setup instructions.

For Pi and Prime Agent, any installed extension with a web_search tool counts as a provider.

In native setup

nanh config <harness> follows the same rules and keeps your --no-search or --force-search choice on --refresh. nanh config --status shows it.

TOKEN BUDGET AND CONTEXT

Two options to keep a session under control:

Session budget

--session-max-tokens limits the input and output tokens of a launch. It counts every request, including compaction and auxiliary models.

When the limit is reached, the agent gets a notice and stops making requests. Your conversation is kept: start a new launch with a higher limit and resume it.

It needs the local gateway, so it does not work with --no-chat-gateway.

Context

--context sets roughly how many tokens the agent uses before compacting the conversation. The agent may compact a little earlier.

OPTIONS

Recommended launch options

Advanced native setup commands

Other commands

CLI UTILITIES

HELP AND PRIVACY

Troubleshooting

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

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.

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.

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.