Automation and agents

NSX is built to be driven by tools as well as by people. This page is what an agent working on an NSX app, or on NSX itself, should know before it starts writing.

Read structured output, not help text

Never parse help text: the command tree, the environment report and the module catalog are all available as JSON, and anything beyond inspection is better done by importing the Python API than by shelling out. The Python API guide lists the surfaces and their shapes.

Find modules by what they do

Module manifests carry summary, capabilities, use_cases, anti_use_cases, agent_keywords, example_refs and composition_hints precisely so that a module can be selected without reading its source. nsx module search matches across all of them.

anti_use_cases is the field that saves the most time. It rules a module out, which is usually the faster half of the decision.

Respect the generated boundary

Some of an app is yours to edit and some is regenerated. Writing to the wrong half produces work that disappears at the next nsx configure.

Edit	Do not edit
nsx.yml, src/, CMakeLists.txt	cmake/nsx/, boards/, modules/, build/

Changing a module means changing the module, not its vendored copy. See Custom modules.

Change intent, then re-resolve

The order matters, because the lock is generated from the manifest and not the other way around:

1. Edit nsx.yml, or use nsx module add and nsx module remove, which edit it for you.
2. Run nsx lock to re-resolve, or let nsx configure do it.
3. Run nsx sync to make modules/ match, or let nsx configure do it.

Never hand-edit nsx.lock. It records commits and content hashes that nsx sync --frozen verifies, so an edited lock is a lock that will fail its own check.

Verify without changing

When you need to know whether a tree is consistent rather than to make it consistent:

nsx lock --check     # read-only, non-zero if the lock is stale
nsx sync --frozen    # fails on drift instead of correcting it
nsx outdated --exit-code --json

These are the right calls in any automated context, because they cannot silently rewrite what they were asked to inspect.

Do not invent capability claims

Everything NSX says about which boards, SoCs and toolchains a module supports comes from that module’s own manifest. It is a declaration by its author, not a record of a hardware run. The same is true of an example’s status and boards_tested front matter.

When summarizing for a user, carry the distinction through: say declared compatible, not validated or supported. If you cannot find a source of record for a claim, leave it out rather than filling the gap.

The same applies to anything numeric about silicon. Power figures, memory sizes and clock speeds belong to a datasheet or to a file in the repository, and a page here that quotes one names the file it came from.

Working on NSX itself

The repository’s own AGENTS.md is the canonical instruction set for changing NSX: architectural choices, working rules, environment escape hatches, schema versioning and the regressions to avoid. Read it before changing behavior rather than inferring the rules from the surrounding code.

Two things from it are worth repeating here because they shape how a change is reviewed: NSX is the single source of truth for app generation and module metadata, and schema changes are deliberate, versioned events rather than silent additions.