Flash your board

The first time you connect a board, Kog performs a one-time setup: it downloads the prebuilt Kog runtime firmware for your chip and flashes it. After that, deploying your app takes about a second — only the tiny app bundle moves.

First flash

npm run dev     # with the board plugged in — flashing happens automatically
# or explicitly:
npx kog flash

What happens:

1. Detection — the CLI scans USB serial ports and identifies your board by its USB identifiers and chip handshake. ESP32-S3/C3/C6 boards need no drivers on macOS, Windows, or Linux.
2. Runtime download — the prebuilt runtime image matching your chip, memory configuration, and CLI version is fetched (a few MB) and cached.
3. Flash — bootloader, partition table, runtime, board configuration, and your app are written in one pass. Flashing is implemented in pure Node (no Python, no esptool install).
4. Wi-Fi handoff (optional) — while still connected over USB, the CLI can hand the device your Wi-Fi credentials so future development is wireless.

Typical first-flash time: under a minute. Subsequent kog dev sessions skip straight to pushing your app bundle (~1 second).

When the runtime updates

Your app bundle declares the runtime ABI it was built against, and the CLI checks the device before pushing. If they've drifted apart you'll see exactly what to do:

Device runtime is ABI 3; your Kog CLI builds ABI 4.
Run `kog flash --runtime` to upgrade the board (your app and settings are preserved).

Which boards work?

• Blessed boards (tested by us, prebuilt images hosted): see Boards. The reference targets are the Waveshare ESP32-S3-Touch-LCD-1.46B and the ESP32-2432S028R "Cheap Yellow Display".
• Any board with supported display/touch controllers: works with the generic prebuilt image plus a board.yaml describing your wiring — still no compiling.
• Anything else: kog firmware build compiles a custom runtime from your board.yaml, auto-installing a managed toolchain. You still never leave the Kog workflow. See Boards & custom hardware.