Adding a harness

Bring your own agents. If a runtime speaks ACP over stdio, one small TOML file is enough to make it launchable, addressable, and wakeable like any built-in — no Rust, no rebuild, no fork.

Nexus ships with claude, codex, opencode, and hermes. Everything below adds a fifth.

Pick an id

The file you write is named after the harness id, and the id is what you type at nexus launch <id>. It must be lowercase ASCII matching ^[a-z][a-z0-9_-]{0,63}$ — a letter first, then letters, digits, -, or _, up to 64 characters. Ids are an open set: nothing enumerates them, so a new one needs no contract or type change.

Write the manifest

Create <NEXUS_HOME>/harnesses/<id>.toml — ~/.nexus/harnesses/goose.toml for a harness called goose:

[command]
program = "goose"                 # required: the executable that speaks ACP on stdio
args = ["acp"]                    # optional: arguments passed before anything Nexus adds
cwd = "/opt/goose"                # optional: pin a working directory; default is the launch cwd

[command.env]                     # optional: environment for the spawned process
GOOSE_MODE = "acp"

program is the only required field. An empty program or any field the schema does not know is rejected.

Manifest environment is applied first, then Nexus layers its own per-runtime identity variables on top. A manifest therefore cannot replace NEXUS_AGENT_ID, NEXUS_CLIENT_KEY, or the other daemon-issued launch values — that is what keeps the runtime’s bus identity trustworthy.

Restart and launch

Manifests are read once, at daemon startup, in deterministic id order:

nexus daemon restart
nexus launch --headless --name goose-worker goose

Manifest harnesses are headless-only. The command belongs to the ACP adapter and is deliberately not advertised as a TUI program, so nexus launch --tui goose fails closed rather than spawning something that cannot be attached.

Note

An invalid or unreadable manifest is logged and skipped on its own. One broken file never stops the daemon or the other harnesses from loading, so check the daemon log if a new id does not appear.

Verify it

Launch it, talk to it, and watch it answer:

nexus launch --headless --name goose-worker goose
nexus members                                  # goose-worker should be listed
nexus dm goose-worker -m "say hello back"
nexus history --with goose-worker

If the launch fails with no headless adapter is registered for harness goose, the manifest was not loaded: check the file name, the id, and the daemon log.

When a manifest is not enough

A manifest covers “start this command and speak ACP.” A runtime that needs more than that — a headed launch you can attach to, native resume, hook or config bootstrap, provider permission flags, or a structured output bridge instead of PTY output — has outgrown a manifest and belongs in a harness crate compiled into Nexus. That is contributor territory rather than configuration: the step-by-step is in the repository, in docs/adding-a-harness.md.

Next

• Harnesses — what each built-in runtime supports.
• Launching agents — headed and headless launches.