nff — let coding agents iterate on hardware

nff is an MCP server that gives coding agents direct control over physical hardware — on the bench during development, and in the field for maintenance and diagnosis.

Connect your board over USB and Claude writes, compiles, flashes, and reads serial output autonomously. Deploy devices with the nff-sdk-c library and Claude can reach them remotely: capture crash state, diagnose failures, and push fixes — without physical access.

nff is the open-source bench CLI of the nff platform — an end-to-end, agent-driven system for developing, shipping, and operating ESP32-class firmware (bench → OTA → fleet diagnosis). This repo (nff) and the device library (nff-sdk-c) are the two MIT-licensed pieces that run on the engineer's laptop and hardware; the hosted backend (fleet broker, OTA orchestration, crash-analysis engine) is proprietary.

you: "Run the sensor init sequence and assert the calibration values over serial"
LLM: [writes firmware] → [compiles] → [flashes ESP32] → [reads serial] → returns structured output

you: "Why did the unit in the field just hard-fault?"
LLM: [captures panic over OTA] → [reads registers + backtrace] → "Stack overflow in your sensor ISR at line 47"

Supported boards: with the PlatformIO backend (now the default in both the shipped Rust binary and the Python implementation) nff is board-universal — any of PlatformIO's ~1000+ boards across ~40 hardware platforms (every ESP32 variant, RP2040/Pico, all STM32 families, classic & megaAVR, SAMD/SAM, Teensy, nRF51/nRF52, Renesas RA / Arduino Uno R4, NXP LPC, Kendryte K210, GD32V/RISC-V, MSP430, TIVA, and many more), with the platform toolchain auto-installed on first build. The classic arduino-cli backend remains available and covers ESP32 (CP210x / CH340) · ESP8266 (FTDI) · Arduino AVR (Uno, Mega, Nano, Leonardo). See Build backends and the full Supported Boards listing.

Bench to fleet, over-the-air. The loop doesn't stop at the bench: nff ota deploy ships the binary you just built to a whole device group — a staged, ECDSA-signed rollout with per-device tracking and automatic rollback — and nff fleet --watch shows it land in real time. See Ship it over-the-air.

Shipped as a single Rust binary. The release artifact is the compiled nff binary built from nff-rs/ — a self-contained executable with no Python runtime required. The Python package under nff/nff/ remains as the reference/prototyping implementation (features are often prototyped there first, then ported to Rust at parity); both are kept in sync, version for version. The Rust port is at full feature parity (CLI commands, MCP server + OAuth proxy, the bench-loop hardening, the PlatformIO build backend, and the nff pi Raspberry-Pi probe).

Quickstart

Get your hardware on the LLM loop in under five minutes.

1. Install

One-liner (recommended — no Python needed):

macOS / Linux:

curl -fsSL https://nanoforgeflow.com/install.sh | sh

Windows (PowerShell):

irm https://nanoforgeflow.com/install.ps1 | iex

Staging versions :

curl -fsSL https://nanoforgeflow.com/install-staging.sh | sh

irm https://nanoforgeflow.com/install-staging.ps1 | iex

Or via pip (depreciated post 0.2.37):

pip install nff

pip install nff fetches a prebuilt wheel containing the same compiled Rust binary for your platform — no Rust toolchain needed at runtime. pip is just the delivery mechanism; the installed nff command is the native binary.

2. Install board cores

On the default PlatformIO backend there is nothing to install here — PlatformIO Core is set up by nff init, and the platform/framework/esptool for your board auto-install on the first build. Just make sure your sketch names a PlatformIO board id (--board esp32dev, etc.).

Both toolchains (platformio / arduino-cli) are auto-installed by nff init/nff install-deps for the active backend if not already present.

3. Plug in your board and run init

nff init                      # local-first, NO sign-in — default PlatformIO backend (board-universal)
nff init --backend arduino    # opt into the arduino-cli backend instead
nff init --cloud              # also sign in to the nff platform (browser) + device onboarding

This single command:

• Needs no account — local mode is the default and init never opens a browser or prompts for sign-in. Pass --cloud (or run nff auth login at any time) to enable the cloud features (repair, agent, OTA, device onboarding). See Local mode is the default below.
• Detects your board by USB vendor/product ID
• Writes ~/.nff/config.json (default device + build backend/board)
• Installs the active backend's toolchain if missing (PlatformIO Core, or arduino-cli)
• With --cloud (or an existing sign-in) on the arduino backend with an ESP32, optionally enrolls the board on the nff platform (flash bootstrap firmware → claim into your dashboard)
• Registers the nff MCP server with Claude Code (claude mcp add --scope user --transport http nff http://127.0.0.1:3010/mcp)
• Starts the MCP server in the background so Claude Code finds it already running — no manual nff mcp needed

  Local mode (default) — no account needed for build/flash/monitor/debug.
  ✓ Found: ESP32 (CP210x) on COM10
  ✓ Config written to ~/.nff/config.json
  ✓ Registered with Claude Code CLI (HTTP MCP on 127.0.0.1:3010)
  ✓ Server running on http://127.0.0.1:3010/mcp

✓ nff configured! Restart Claude Code to pick up the nff MCP server.

The background server runs until you reboot or stop it. After a reboot, run nff mcp (or just re-run nff init) to bring it back up — nff doctor will tell you if it's down.

Local mode is the default

You don't need an nff account to use nff. Compile, flash, monitor, debug, and the MCP tools all run entirely on your machine, and a plain nff init never opens a browser or asks you to sign in. nff doctor reports a clean bill of health for a local-only setup.

Only the cloud features need an account: nff repair, nff agent, OTA, and device onboarding. Opt in whenever you want them with nff init --cloud or nff auth login — signing in also lifts offline mode automatically. nff init --offline (or NFF_OFFLINE=1) persists a hard offline mode that additionally silences the cloud hints until you sign in.

4. Verify

nff doctor

5. Talk to your board

Restart Claude Code (so it picks up the MCP server) and just describe what you want — Claude compiles, flashes, and reads serial through nff:

you: "Flash sketches/blink_esp32 and confirm the LED is toggling over serial"
LLM: [compiles] → [flashes ESP32] → [reads serial] → "LED toggling at 1 Hz, confirmed"

Prefer the CLI directly? The same loop is a one-liner:

nff flash sketches/blink_esp32
nff monitor --timeout 10

Two modes, one tool

Bench development

nff closes the edit–compile–flash–debug loop. Instead of switching between your editor, terminal, and serial monitor, you stay in one conversation. The LLM iterates on firmware in response to serial output, catches exceptions, and reflashes — handling the logistics so you focus on the problem.

Field maintenance

Once a device is deployed, nff becomes your remote window into it. When a bare-metal MCU crashes in the field there is no shell, no SSH, no process table — just a panic on a chip you cannot physically touch. nff captures the crash state (registers, stack, memory, backtrace) and routes it to a cloud AI agent that explains the failure in plain language and drives the recovery. No truck roll. No JTAG probe on-site.

This is the gap Mender, balena, and similar OTA tools cannot fill: they require a living network client running inside the firmware. nff's field mode works precisely when the firmware is dead.

Ship it over-the-air — nff ota

The bench loop ends with a compiled binary; nff ota is how that binary reaches the fleet. One command turns a local build into a staged, signed rollout to a device group — with per-device progress and automatic rollback on failure. The same "push and it's live" motion as a web deploy, for firmware in the field.

you: "The fix is verified on the bench — roll 1.2.0 out to the prod group"
LLM: [compiles] → [ota_deploy v1.2.0 → prod] → [fleet_status] → "18/18 devices committed, 0 rollbacks"

Prefer the CLI directly? A deploy is one line, and a live fleet view is another:

nff ota deploy build/firmware.bin --version 1.2.0 --group prod
# OK: deployment 3f2a… started (v1.2.0)
#   delivered=18 failed=0 skipped=0
#   track it with `nff ota status 3f2a…`

nff ota status        # per-device progress of the latest deployment
nff fleet --watch     # live table: device status, current → target firmware, OTA progress

Signed, staged, and downgrade-proof. The bench builds the binary, but a field device only ever accepts an ECDSA-signed update delivered by the fleet (signing keys live in an HSM) — so the update ships through the platform, never from the bench directly. Versions are strict 3-part semver and must increase: devices refuse downgrades. Rollouts stay staged (--max-in-flight), and a device that fails verification rolls itself back to the previous firmware.

OTA is a cloud feature: it needs a platform sign-in (nff auth login, or nff init --cloud) and refuses to run in offline mode. Deployments run under your project — the platform verifies membership and drives the rollout.

The same capability is exposed to agents as MCP tools — see Fleet & OTA below.

MCP Tools

Bench — hardware & build

Debug — live on-chip (JTAG/SWD)

Pause a running device and inspect it at the source level — like a real debugger, not just serial prints. nff drives OpenOCD + GDB itself (binaries come from the PlatformIO toolchain). Supported targets: ESP32-S3/C3/C6 (built-in USB-JTAG) and STM32 via an ST-Link probe (e.g. on-board on a Nucleo/Discovery); the board is auto-detected from USB. Most tools require a halted target (hit a breakpoint or call pause_execution first); symbols are optional — with no ELF you can still attach and read registers/memory/raw-GDB.

Classic ESP32 / ESP32-S2 have no built-in JTAG: connect an external probe and pass interface= (e.g. ftdi/esp32_devkitj_v1). nff debug check reports the detected chip / OpenOCD / GDB / ELF without touching hardware.

Field — diagnosis & auth

Fleet & OTA

Ship firmware to the field and watch it land — the agent-facing side of nff ota.

All five require platform login — on a not-authenticated error, call authenticate (CLI: nff auth login).

All bench tools fall back to the default device in ~/.nff/config.json when port and board are omitted.

Prefer sketch= (a path) over code=. Write the .ino file to disk first and pass the sketch path, rather than raw source — it keeps the build artifact lookup deterministic. Use compile to check a build with no board attached; use flash only when a port is present.

Demo

Real Hardware

CLI Reference

Command status

What actually ships on the Rust binary today. stable = works; roadmap = present but a stub / not yet implemented. Full detail and the plan behind the roadmap items live in docs/ROADMAP.md.

Real hardware

nff flash sketches/sensor_init
nff flash sketches/sensor_init --board esp32dev --port COM3   # PlatformIO board id (default backend)
nff flash sketches/sensor_init --board esp32:esp32:esp32      # arduino FQBN (NFF_BUILD_BACKEND=arduino)
nff flash sketches/sensor_init --manual-reset                 # for boards without auto-reset
nff monitor --port COM10 --baud 115200
nff monitor --port COM10 --baud 115200 --timeout 15

Supported Boards

On the default PlatformIO backend, nff is board-universal. Pass any of PlatformIO's ~1000+ board ids to --board and the matching platform toolchain (compiler + framework + uploader) installs itself on first build — there is no fixed allow-list and nothing to pre-install.

Architectures & platforms covered

The PlatformIO backend gives nff every PlatformIO development platform — each one a whole family of boards. You don't need any of these in nff's catalog; just pass the PlatformIO board id to --board and the toolchain installs on first build. The table below is the full set of platforms (≈40), each spanning dozens-to-hundreds of individual boards.

Less common platforms PlatformIO also ships (and that nff therefore drives) include nuclei, riscv_gap, samd21, chipsalliance, aceinna_imu, shakti, samsung_artik, and others — see the PlatformIO platforms index for the live, complete list.

Curated families (built-in catalog)

These are the board ids in nff's built-in catalog. The catalog only supplies sensible defaults (PlatformIO platform) so you can name a short board id and nff init can auto-detect — every other board above still builds, you just pass the full PlatformIO id.

Need a board that isn't catalogued (Teensy, SAMD, nRF52, Uno R4, ESP32-P4, …)? Just give its PlatformIO id — e.g. nff compile sketch.ino --board teensy41. Adding it to the catalog (for auto-detect + a short default) is a two-line PR.

USB auto-detect

When you plug a board in, nff resolves it by USB vendor/product ID to a default board id for both backends, so nff init and --board-less commands "just work". A USB-serial chip (CP210x/CH340/FTDI) is shared by many boards, so this is a default you can override with --board.

The arduino backend (NFF_BUILD_BACKEND=arduino) is limited to the FQBN column above plus whatever cores you arduino-cli core install. The PlatformIO backend is the one that makes the rest of the families above available.

Self-Update

nff keeps itself current the way Claude Code does. After a command finishes, a throttled (default: once per 24 h) detached background check downloads the latest GitHub Release binary, verifies it against the release's SHA256SUMS, sanity-runs it, and atomically swaps it into place — the next invocation runs the new version, and a ✓ nff updated itself to vX.Y.Z notice appears on stderr. Nothing is added to the latency of the command you ran.

• Only standalone installs auto-update (the install.sh / install.ps1 one-liners). pip/pipx/uv wheel installs (being deprecated) just get a "new version available — reinstall standalone" notice; dev checkouts are left alone.
• nff update runs the same flow in the foreground; nff update --check only reports (exit 2 when a newer release exists — scriptable).
• If an update fails, nff calls the doctor: nff update runs nff doctor automatically for diagnostics, and a failed background attempt is surfaced on your next command with a pointer to nff update. nff doctor also shows update health (channel, freshness, last error).
• Opt out with NFF_NO_AUTO_UPDATE=1 (per-run) or "update": {"auto": false} in ~/.nff/config.json (persistent); nff update keeps working either way. NFF_UPDATE_EVERY_HOURS tunes the cadence.
• A running nff mcp server keeps its old image through a swap — restart it (nff mcp restart) to pick up the new version.

Update state lives in ~/.nff/update.json; the background job logs to ~/.nff/update.log.

Config File

~/.nff/config.json, written by nff init and editable by hand:

{
  "version": "1",
  "default_device": {
    "port": "COM10",
    "board": "ESP32 (CP210x)",
    "fqbn": "esp32:esp32:esp32",
    "baud": 115200
  },
  "build": {
    "backend": "platformio",
    "board": "esp32dev"
  }
}

build.backend selects the toolchain (platformio default, or arduino) and build.board holds the PlatformIO board id; the arduino backend uses default_device.fqbn instead. The NFF_BUILD_BACKEND env var overrides build.backend per-run.

Claude Code Skills

nff ships Claude Code skills bundled inside the package:

/nff

Skill files live at nff/skills/ (the source of truth — edit them there) so they ship with every pip install nff, and are also mirrored in .claude/commands/ for project-level use. Copy them into ~/.claude/commands/ to make the slash commands available globally.

The /wokwi-diagram simulation skill moved to the nff-sim package.

Repository Structure

nff/
├── nff/                         # Python package — reference / prototyping implementation
│   ├── cli.py                   # Click CLI — wires every subcommand
│   ├── config.py                # ~/.nff/config.json read/write
│   ├── mcp_server.py            # streamable-HTTP MCP server (Bearer-authed /mcp)
│   ├── commands/
│   │   ├── init.py
│   │   ├── compile_cmd.py       # port-free build check
│   │   ├── flash.py
│   │   ├── monitor.py
│   │   ├── connect.py           # autonomous log-analysis + repair loop
│   │   ├── repair.py            # route crash output to the diagnosis server
│   │   ├── auth_cmd.py          # nff auth login / status / logout
│   │   ├── ota.py               # nff ota — OTA rollout to a device group
│   │   ├── fleet.py             # nff fleet — live fleet/OTA view
│   │   ├── provision.py
│   │   ├── doctor.py
│   │   ├── clean.py
│   │   ├── install_deps.py
│   │   └── mcp_cmd.py
│   ├── tools/
│   │   ├── boards.py            # USB ID detection + PlatformIO board catalog
│   │   ├── serial.py            # serial read/write/stream/reset
│   │   ├── toolchain.py         # backend dispatcher + arduino-cli/esptool wrappers
│   │   ├── backends/
│   │   │   └── platformio.py    # PlatformIO backend (project scaffold, pio run)
│   │   ├── installer.py         # arduino-cli auto-install
│   │   ├── ota_client.py        # /api/ota/* client (deploy, status, fleet snapshot)
│   │   └── auth.py              # diagnosis-server token handling
│   └── skills/                  # /nff skill (ships with the package)
├── nff-rs/                      # Rust port — the shipped binary (full parity)
├── sketches/
│   ├── blink_esp32/
│   └── servo_button/
└── .claude/
    └── commands/
        └── nff.md               # /nff Claude Code skill

The Rust crate under nff-rs/nff/ is the shipped binary and is at full feature parity with the Python package — every CLI command and MCP tool runs natively (no Python runtime). Build it with cargo build --release (binary at nff-rs/target/release/nff). The Python package under nff/nff/ is the reference/prototyping implementation and is kept in sync version-for-version; when you add a feature, land it in both so the two never drift.

Linux: Serial Port Permissions

sudo usermod -aG dialout $USER
# then log out and back in

nff doctor detects this and prints the fix.

License

MIT — see LICENSE.
Copyright (c) 2026 Gauthier Lechevalier