The OS runs on the device. Your browser is the rich operator console. One ESP32‑S3, no PSRAM, ~512 KB of RAM — turned into a real, modern, multi‑app OS with an offline AI assistant, a bilingual voice, a desktop‑class web shell, native games, a security lab, on‑device transcription and offline image generation.
ESP32‑S3 / M5StampS3 · ESP‑IDF firmware · PWA web shell · English‑only codebase
Free for noncommercial use · commercial use requires a paid license → niki070585@gmail.com
Most Cardputer firmwares are a menu of tools. NucleoOS is an actual OS — a registry of capability‑scoped apps, an event‑sourced bus, pairing/auth, OTA with rollback, an i18n engine, notifications, a power manager, and two complete user interfaces that share one contract:
| Native firmware (on the 240×135 screen) | NucleoOS Web (any browser on your LAN) | |
|---|---|---|
| Runs | On the ESP32‑S3 itself | Served by the device, rendered in your browser |
| Strength | Always there, no host, smartwatch‑style UX | Desktop‑class windows, mouse + keyboard, big screen |
| Examples | Games, security tools, sensors, media, ANIMA chat | File manager, spreadsheet, Paint+AI, Game Center, IDE |
| Design rule | Large fonts, every pixel, autocomplete/history/1‑9 quick‑select | Real windows, fullscreen apps, drag‑and‑drop |
The split is deliberate: heavy work goes to the browser, never to the 18 KB device heap. That is the single idea that lets a no‑PSRAM microcontroller host an experience this large.
The native on‑device UI (240×135) — launcher → music → video — captured live over Wi‑Fi from the device's own
GET /api/screen endpoint, which streams the physical panel as a BMP, no canvas, ~0 heap.
NucleoOS runs on both the original M5Stack Cardputer and the newer Cardputer ADV — a single universal binary auto‑detects which one you have (keymap + audio codec HAL) at boot, so you build once and flash either.
Left: original Cardputer (M5StampS3). Right: Cardputer ADV (Stamp‑S3A, bigger battery, IMU, 3.5 mm out). Product photos © M5Stack.
ANIMA is NucleoOS's assistant, and it runs in two places at once:
- On the firmware — a real offline NL engine in C (retrieval cascade L0/L1/L2, neuro‑symbolic reasoning, knowledge graph, math/units, learn & profile tiers). No cloud, no LLM, grounded by construction — so it never hallucinates a fact it doesn't have.
- In the web shell — the same assistant compiled to WebAssembly, running entirely in your browser: offline, private, instant. It opens apps, does math, tells time/date, creates files, answers questions and learns what you teach it — nothing leaves the device.
🔊 Bilingual offline voice. ANIMA speaks — a concatenative TTS engine (IT/EN) that
pre‑vocalizes a finite, grounded vocabulary on the PC and pastes the right clips at runtime:
natural voice, ~zero RAM, completely offline. It reads the time to the exact minute, confirms
launches ("Opening music"), states status — and politely says "read it on screen" for anything
that shouldn't be spoken aloud. See docs/tts.md.
When you do want a frontier model, NucleoOS wires it in cleanly:
-
OS‑wide copilot — summon AI from anywhere with
Ctrl/⌘ + Space. -
Pluggable providers — Claude, Groq, Grok (xAI), Gemini. Configure one (or several, with automatic fallback). Keys are stored on the device SD, never logged, and the browser talks to the provider directly — the Cardputer isn't in the loop.
-
AI Chat talks straight to the model; ANIMA stays offline. You choose per task.
-
ANIMA Code — a sandboxed JavaScript runtime in the browser with an
os.*API (os.fs,os.http,os.anima,os.notify): write a script, hit Run, drive the OS. -
ANIMA Chat / Agents — multi‑turn chat and a browser‑hosted multi‑agent runtime for online work.
- On‑device transcription — speak into the Cardputer mic and watch text appear, on‑device, via a Vosk WASM model. IT/EN, summarize, screen‑off while listening to save battery.
- Record & transcribe in real time, remotely — start a recording on the Cardputer and stream it
live to NucleoOS Web (
/api/rec/stream) for real‑time transcription on the big screen. - Mic Spectrum — a live FFT analyzer on the native screen.
Paint is a full image editor — layers, tools, adjustments, transforms — with an AI side (Atelier) that generates and manipulates images locally via WebGPU, no server: "create a cat icon", "remove the background", "brightness +20", "rotate right". Heavy pixels live in the browser GPU; the device just stores the result.
- Native multiplayer over ESP‑NOW (no router): Pong, Snake Duel, Tank Duel, plus a full beat‑'em‑up (Scorribanda), Pinball, Tanks artillery, Poker, Slots, Yahtzee, Dice and 3D constellations — each rebooting into a fresh heap for maximum RAM.
- Game Center (web) — peer‑to‑peer over WebRTC with the Cardputer as signaling: Tic‑Tac‑Toe, Connect 4, Pong — 2‑player or vs ANIMA (offline brain, or an LLM brain when online).
- Film player (native) — plays
.nfv(MJPEG + MP3) straight off the SD with seek. - MP3 player (native) — dual‑mic aware, browses folders, reads duration from headers.
- Radio (native) — multi‑station internet radio with a twin web app.
A clean‑room offensive/defensive toolkit (native firmware apps):
- WiFi Sniffer — promiscuous capture →
.pcapon SD, live breakdown, radiotap, radar view. - Evil Portal — captive‑portal testing.
- WiFi Attacks — deauth/beacon/probe suite (clean‑room).
- BLE Suite — scan / spam / iBeacon.
- Ethernet (W5500) — raw L2/L3 MACRAW attacks over the SD bus.
- Payloads / BadUSB — DuckyScript runner with dry‑run.
- USB Keyboard PRO — HID injection, macros, IT/US layouts.
Turn the Cardputer into a Swiss‑army tool: Torch, Bubble Level, Protractor (goniometer), Alarm (siren armed by microphone + accelerometer + IMU), Pedometer (step counter), Mic Spectrum, plus Clock, Calendar, Weather, IR Remote, QR and PixelFix.
A real SSH terminal that reaches your hosts through a tiny self‑hosted bridge (no third party) — available as a native app on the Cardputer and as a full web terminal with saved hosts.
File Commander, Spreadsheet (SUMIFS/VLOOKUP/IF with an ANIMA copilot), a live System Monitor, Settings Control Center, Notepad, Calculator, DOSBox, and more — real windows, fullscreen, drag‑and‑drop, Start menu and search.
📸 More screenshots — web shell apps
 |
 |
 |
 |
 |
 |
The apps are the surface. These are the engineering bets that make them possible on a no‑PSRAM microcontroller — and several have no equivalent in other Cardputer firmwares.
ANIMA's offline brain is written once in C and runs in three places, certified to give the same answer in each:
- On the ESP32‑S3 (the device firmware).
- In your browser — the exact same C compiled to
wasm32(anima-local.wasm), so the web shell's assistant is offline and private, not a reimplementation. - On the PC host harness (
anima.exe) for development and gates.
A parity gate runs every query through the WASM module and the native build and asserts byte‑identical replies; a web‑contract gate pins every JSON field the chat UI reads. The "cascata WASM" isn't a port — it's literally the device's C, recompiled.
query → L0 intent/FAQ string match (<1 ms, no SD, no model) 70–90% of use
L1 binary Hamming (popcount) coarse + int8 rerank, confidence‑gated
L2 MOSAICO span‑stitch — verbatim, attributed (never fabricated)
L3 optional cloud LLM — else an honest "I don't know"
- No‑FPU‑friendly: Matryoshka binary embeddings (~64 B), distance =
popcount(a XOR b)— pure integer math, ideal for an MCU. int8 rerank only for the few survivors (~tens of KB/query). - Matryoshka speculative prefetch: the 16‑dim embedding prefix prefetches the likely SD clusters on core 1 while core 0 finishes the full encode — compute overlaps slow storage.
- Evidential abstention (CRAG‑style gate): high → frozen answer, medium → stitch, low → refuse. It never hallucinates a fact it can't support. Live data (time/battery/files) always bypasses the cache.
- Neuro‑symbolic core: HDC/VSA hyperdimensional reasoning (XOR/popcount bind‑bundle) + a permutation‑KGE deductive engine (inverse/transitive/multi‑hop) + a math/physics/vector solver, with a proof‑carrying mode (NSPCG) in Forge.
The device never streams model weights. Anything heavy is offloaded to the browser: WebLLM (Qwen2‑0.5B, WebGPU) and wllama for real in‑browser LLM work (Forge), ONNX Runtime Web for offline diffusion (Paint/Atelier), ffmpeg.wasm for Video Studio.
A clean‑room MACRAW Layer‑2/3 engine (nucleo_eth) over a self‑written W5500 driver — not
lwIP, not Bruce source. It includes a hand‑rolled DHCP client that self‑configures with no
TCP/IP stack, OUI vendor fingerprinting, and operations most firmwares lack:
| Op | What it does |
|---|---|
| Scan | ARP sweep of the subnet → host list + OUI vendor fingerprint |
| MITM | bidirectional ARP spoof victim↔gateway — reversible (heals the caches it poisoned on exit) |
| Poison / Starve / Flood | ARP chaos · DHCP pool exhaustion · switch‑CAM MAC flood |
| Rogue DHCP | answer DISCOVERs as a rogue server → redirect router/DNS to us |
| PCAP | passive capture to an SD .pcap |
Strict discipline: exactly one op at a time (start = stop‑heal‑free the previous), every active
attack is consent‑gated, and the app declares NX_NET_APP so the OS reclaims ~70 KB while it runs.
Every demanding feature respects a tight set of RAM tricks, validated on hardware:
- Exclusive mode — apps reclaim ~47 KB by taking httpd + ANIMA L1 + mDNS down for their run.
- Heap‑on‑enter — big buffers allocate on entry, never in
.bss(a.bssarray once bricked the ADV). - Solo boot — an RTC flag skips httpd/mDNS for a contiguous heap; each game reboots into a fresh one.
- Canvas‑free OTA — the framebuffer auto‑frees at idle so an update finds enough contiguous heap.
- Heavy‑work arbiter — one TLS session at a time (503 if busy); online ANIMA gated on
block ≥ 18 KB AND free ≥ 40 KB. Plus FATFS WL‑sector‑512 (+33 KB), web‑focus screen‑off (+32 KB), and-Os/Lua‑strip size work (≈37 % flash free).
- Universal binary — one image auto‑detects the original Cardputer vs ADV (TCA8418 keymap + ES8311 codec HAL) at runtime: build once, ship to both.
- Event‑sourced bus — append‑only state deltas → observability, replay, undo; extends across ESP‑NOW peers (the swarm/CHORUS model) for shared clipboard, multiplayer and sensor mesh.
- Multi‑runtime apps —
web(zero device RAM) ·vm(sandboxed on‑device bytecode) ·service(native C) ·elf(PSRAM‑gated). Install/run without reflashing. - OS services — capability‑scoped manifests, OTA A/B with rollback, PIN pairing + cookie auth,
delta SD‑sync (never
/MIR), OS‑wide live IT/EN i18n, notifications, an OS‑wide mic gate and download gate (Web Locks), and a service‑worker update gate. - Robustness gates — a hallucination stress suite (485 metamorphic sentences, 40 gates), corpus dedup/quality gate, and an auto‑evolving knowledge graph (Wikipedia + teacher‑LLM, AUG‑192 encoder).
| Category | Apps |
|---|---|
| Assistant & voice | ANIMA chat · Recorder (MP3, dual‑mic + live transcription) · Mic Spectrum (FFT) · Voice Trainer / keyword + PTT (AVCEB MFCC·CMN·DTW) |
| Security — Wi‑Fi/BLE | WiFi Sniffer (→ .pcap) · Evil Portal · WiFi Attacks (deauth/beacon/probe) · BLE Suite (scan/spam/iBeacon) · Beacon |
| Security — wired/USB | Ethernet/W5500 L2‑L3 engine · Payloads / BadUSB (DuckyScript) · USB Keyboard PRO (HID, macros, IT/US) |
| Media | Film player (.nfv MJPEG+MP3, seek) · MP3 player · Radio (multi‑station) · Photos |
| Instruments & sensors | Torch · Bubble Level · Protractor · Alarm (mic + accelerometer + IMU) · Pedometer · Weather · IR Remote · QR · PixelFix · Screensaver |
| System | WiFi manager · Settings/Theme · Clock · Calendar · Notepad · Calculator · System Monitor · Notifications · Info · Mail (SMTP) · SSH terminal |
| Games | Pong · Snake Duel · Tank Duel · Tanks (artillery) · Scorribanda (brawler) · Pinball · Poker · Slots · Dice · Yahtzee · Constellations (3D) · Reactor · Sand Garden — via the GameFront carousel |
| Category | Apps |
|---|---|
| AI | ANIMA (offline WASM) · AI Chat (Claude/Groq/Grok/Gemini) · ANIMA Code · Agents · OS‑wide copilot |
| Creativity & media | Paint + Atelier (WebGPU image gen) · Video Studio · Video Player · Media Player · Radio · QR |
| Productivity | File Commander · Spreadsheet (+ANIMA copilot) · Notepad · Calculator · Calendar · Tasks · Archive Manager · Mail |
| Dev & system | Code Runner · Terminal · SSH · System Monitor · Settings · Log Viewer · Updates · Recycle Bin · Help · Browser |
| Voice | Transcription (Vosk WASM, on‑device + remote realtime) · Recorder · Voice Manager · Dictation |
| Play & connect | Game Center (WebRTC P2P) · Games · DJ · DOSBox (+ DOS Importer) · Nearby · Swarm |
Apps are capability‑scoped (each declares its permissions) and most cost ~0 device RAM — they are files on the SD, rendered by your browser. The registry is the single source of truth.
NucleoOS exists because the hardware is brutal. Every feature above respects these:
- RAM: ~512 KB SRAM, no PSRAM. Runtime heap ~18 KB; the real enemy is fragmentation
(httpd + ANIMA L1 + workers), not CPU. Heavy data never loads on the device — it goes to the
browser. Native apps allocate on‑enter and run exclusive. See
docs/memory-budget.md. - Battery: ~120 mAh — energy is a first‑class system resource; every service declares a budget.
- Storage: microSD (system in flash, content on SD).
- Recovery first: OTA updates fail without bricking (A/B partitions + rollback).
docs/ Engineering specs — one focused file each (the canonical knowledge base)
schemas/ JSON Schemas — shared contract for firmware / PC / Android
registry/ Live OS registry: installed apps, settings, file associations, app aliases
apps/<id>/www/ One folder per web app + manifest.json (.gz built alongside)
firmware/ ESP‑IDF firmware (boot, SD, registry, HTTP/WS, ANIMA C core, native apps)
components/nucleo_app/ Native firmware apps (games, security, sensors, media, ANIMA…)
components/nucleo_anima/ Offline NL engine (retrieval cascade, KG, reasoning)
components/nucleo_tts/ Offline concatenative bilingual voice
components/nucleo_*/ HAL + services: codec, httpd, ir, ble, smtp, …
web/shell/ Desktop shell PWA (windows, taskbar, Start, copilot, i18n)
tools/ Dev tooling: validators, the host harness, the device simulator, deploy/flash
tools/anima-host/ Host gates — compile the REAL firmware C and run it on the PC
Start every orientation from the relevant file under docs/*.md — it's the source of truth,
one focused engineering spec per topic; prefer reading it over re‑deriving.
Don't iterate by flashing. The host harness compiles the real ANIMA C and runs it on the PC:
npm run anima -- "what is nucleoos" # one‑shot npm run anima # interactive REPL
npm run anima:gate # the ANIMA regression gate (must be green before any flash)
npm run validate # registry + manifest schema + cross‑reference checkFor web/shell work, run the zero‑dependency device simulator — it mirrors the device API and serves every app, so you verify in a browser without touching hardware:
node tools/serve-shell.mjs # http://localhost:5599Verification matrix: npm run validate · i18n:gate · gz:check · gen:api:check ·
anima:gate · test:all. See docs/debugging.md.
All screenshots above are captured from this simulator running the real shell and apps.
tools/release.ps1 # gate → build → assemble deploy/sd → SD delta‑sync → OTA
tools/release.ps1 -FirmwareOnly # OTA the firmware only
tools/flash.ps1 # gate → build → flash over USB (confirm only)It's one universal binary — the same image auto‑detects the board (original Cardputer vs ADV)
at runtime, so you build once and fan out. The ANIMA gate must be green before any flash
(release.ps1/flash.ps1 enforce it). See docs/releasing.md.
NucleoOS ships tools that probe and transmit on radio and wired networks — Wi-Fi (scan, deauth, beacon, Evil Portal, PMKID / handshake capture), Bluetooth LE, Ethernet L2/L3, infrared, USB-HID (BadUSB / DuckyScript), and the FIDO security-key stack. These are provided for authorized security testing, research, and education only.
- Use them only on networks, devices, and systems you own or have explicit written permission to test.
- You alone are responsible for complying with every applicable law and regulation in your jurisdiction — including computer-misuse, unauthorized-access, interception / wiretap, privacy, and radio-spectrum rules. Active transmission (deauthentication frames, beacon / BLE floods, infrared, jamming) is restricted or outright illegal in many countries.
- Do not use NucleoOS against any network, device, or account without authorization. Unauthorized access, disruption, or interception can be a criminal offense.
- NucleoOS is provided "as is", without warranty of any kind. The authors and contributors accept no liability for any damage, loss, or legal consequence arising from its use or misuse.
By building, flashing, or running this software you accept these terms and agree to use it lawfully and ethically. If you do not agree, do not use it.
PRs welcome — see CONTRIBUTING.md (includes a short contributor agreement so the
project can stay dual-licensed). Third-party components and their licenses are listed in
THIRD_PARTY.md.
PolyForm Noncommercial License 1.0.0 — free for any noncommercial use (personal, study, research, hobby, non-profit, education, government).
Commercial or production use requires a paid commercial license — see
COMMERCIAL.md. Want to ship NucleoOS in a product? Get in touch:
niki070585@gmail.com.
© 2026 indecenti. All rights reserved. NucleoOS bundles third-party components under their own
licenses (some copyleft) — see THIRD_PARTY.md.
NucleoOS — a microcontroller that thinks it's a workstation. Built for the M5Stack Cardputer · English‑only codebase · designed for the worst case.