E ESPClaw Embedded agent runtime GitHub

ESPCLAW // EMBEDDED AGENTS FOR REAL HARDWARE

Put a programmable agent runtime on a board that actually has to behave.

ESPClaw turns ESP32-class boards into inspectable, OTA-updatable agent systems with reusable Lua components, persistent tasks and behaviors, a local admin UI, and real hardware tool calls.

Flash a board Launch browser lab Download release
Boards ESP32 · ESP32-CAM · ESP32-S3
Channels Web · UART · Telegram · Simulator
Runtime Apps · Components · Tasks · Behaviors · Events

PROJECT OVERVIEW

An embedded agent runtime, not just another firmware image.

ESPClaw is built for boards that have real constraints: limited RAM, unstable power, real sensors, flaky radios, and operators who need to understand what the system is doing. The design goal is to keep the stack inspectable while still letting an LLM orchestrate serious local behavior.

GOAL

Shorten the loop between idea and hardware behavior.

Flash once, then iterate with OTA, installable Lua apps, reusable components, and a tool-using agent loop instead of rebuilding for every change.

PHILOSOPHY

Boring architecture, visible state, reversible operations.

Workspace files, logs, tasks, behaviors, and model interactions are exposed as local runtime surfaces instead of disappearing into a cloud-only control plane.

SHAPE

Components for reuse. Apps for features. Behaviors for persistence.

ESPClaw encourages community-shared drivers and modules while keeping end-user features as explicit installable artifacts.

CAPABILITIES

What the stack can do today.

Hardware runtime

  • GPIO, PWM, ADC, I2C, SPI, UART, BLE scan
  • Camera capture on ESP32-CAM class boards
  • Board profiles and named pins/buses

Agent surfaces

  • Web admin chat, UART shell, Telegram, simulator
  • Tool-calling loop with execution-choice guidance
  • Shared global YOLO operator policy

Programmability

  • Installable Lua apps and shareable components
  • Tasks, behaviors, events, and event watches
  • Chunked uploads and install-from-file / URL / manifest

Operator ergonomics

  • Browser flashing and OTA update paths
  • Workspace file APIs and context chunking
  • New in-memory `/api/logs` and `system.logs` tail

RUNTIME MAP

How ESPClaw is structured.

Channels
Web · UART · Telegram · Browser Lab
Agent loop
Prompt contract · tool calls · retries · safety
Workspace
apps / components / sessions / blobs / memory
Runtime
hardware / network / OTA / tasks / behaviors / events
component

Reusable Lua module or driver you can share with the community.

app

Installable feature bundle built from components and local logic.

task

Live running instance of an app for “run this now” automation.

behavior

Persisted task definition that survives reboot and can autostart.

event

Decoupled local signal for waking event-driven tasks and pipelines.

BROWSER LAB

Try ESPClaw in the browser before you ever flash a board.

This lab runs the real ESPClaw C runtime compiled to WebAssembly: workspace bootstrap, tool execution, components, apps, tasks, behaviors, events, and the in-memory log ring all come from the same runtime core the firmware and host simulator use. WebLLM can drive the agent loop locally in-browser, or you can point the page at an OpenAI-compatible endpoint.

MODEL

Agent provider

Idle. Pick a model and initialize the browser lab.

SCENARIOS

Seed prompts

BROWSER RUNTIME

WASM runtime snapshot

CHAT

ESPClaw browser runtime

Local-first

This tab is exercising the real ESPClaw runtime in WASM, not a fake demo kernel.

TOOL TRACE

Executed calls

LOG TAIL

`system.logs` surface


              

            

          

        

      


      

        

          
FLASHER

          
Browser flashing for the current release.

          

            The page pulls firmware artifacts and esp-web-tools manifests from GitHub Releases.
          

        

        

          

            Release
            Loading…
          

          

            Published
            —
          

          

            Fallback
            Downloadable bundles
          

        

        

          

            
DISCOVERY

            
Loading release assets…

            
The page is querying the latest GitHub release and matching flash manifests.

          

        

      


      

        

          
OPEN SOURCE

          
Project goals, capabilities, and where to go next.

        

        

          
            Repository
            GitHub
            
Source, issues, releases, CI, and project history.

          
          
            Docs map
            README
            
Architecture, quick start, support matrix, and release notes.

          
          
            Reuse model
            Components
            
Shareable drivers, manifests, and install-from-url flows.

          
          
            Runtime testing
            Simulator
            
Host and simulator flows for testing without touching hardware.