edge-agents Runtime Quickstart — Open-Source Agents on Pi, Jetson & STM32MP25

// last reviewed 2026-06-04 · ForestHub Editorial Team

edge-agents Runtime Quickstart

edge-agents is the 30 MB open-source AI agent runtime for edge devices. Offline by default — GPIO, UART, MQTT as first-class nodes. A visual workflow builder produces a *.workflow.json spec, and a Go execution engine runs it as a binary (in Docker, HTTP API on :8081) on Linux / MPU-class edge hardware. This page is a copy-paste terminal quickstart from a firmware developer’s point of view.

Source: github.com/ForestHubAI/edge-agents · Published by ForestHub.ai.

Hardware honesty (read first): edge-agents runs on boards that boot Linux — Raspberry Pi 5, NVIDIA Jetson Orin Nano, STM32MP25 (a Cortex-A35 MPU running Linux, not a bare-metal Cortex-M microcontroller), and Bosch Rexroth ctrlX CORE. It does not run on a bare-metal STM32H7, STM32L4, or ESP32 — those are a different hardware class covered by the ESP32 and STM32 firmware pages. Bare-metal MCU (Cortex-M) support is on ForestHub’s roadmap, not shipping today. See the full Hardware Support matrix.

1. Install the CLI (no clone)

npm i -g @foresthubai/workflow-cli

This installs fh-workflow, the command-line entry point for opening, validating, and migrating workflow specs. Full command list: the fh-workflow CLI reference.

2. Open the visual builder on a workflow

fh-workflow open my.workflow.json

The builder is a React Flow visual editor (TypeScript). Nodes are the agent’s building blocks: sensor/transport nodes (GPIO, ADC/DAC/PWM, UART/Serial, MQTT), an LLM node, and a web-search node. The output is a plain *.workflow.json file.

3. Run the Go engine container (arm64 → Pi 5 / Jetson / STM32MP25 / ctrlX)

The engine is a Go binary that runs in Docker. Cross-build it for arm64 and run it; the HTTP API listens on port 8081.

# Run the engine container (cross-build for arm64 → Pi 5 / Jetson / STM32MP25 / ctrlX)
cd go
docker buildx build --platform linux/arm64 -t edge-agents/engine:arm64 --load .
docker run --rm -p 8081:8081 edge-agents/engine:arm64

4. Configure the engine

The engine is driven entirely by environment variables pointing at config files:

LLM providers supported: Anthropic, OpenAI, Gemini, Mistral, and a local SLM (llama.cpp / vLLM / Ollama / any OpenAI-compatible server).

5. Call a local model, stay offline

The engine can delegate reasoning to a local small language model so the whole stack stays offline:

# Local SLM (llama.cpp) the engine can call — fully offline
docker pull ghcr.io/ggml-org/llama.cpp:server-b8589
docker run --rm --network host -v "$PWD/models:/models:ro" \
  ghcr.io/ggml-org/llama.cpp:server-b8589 \
  --model /models/gemma-3-270m-it-Q4_0.gguf --host 0.0.0.0 --port 8090

Point the engine’s LLM node at http://localhost:8090 (OpenAI-compatible) and no request leaves the device.

6. Generate a workflow with the Claude Code skill

# Generate workflows with the Claude Code skill
npx skills add ForestHubAI/edge-agents --skill workflow-generate

Repo & CTA

$ npm i -g @foresthubai/workflow-cli

FAQ

Q: Does this run on a bare-metal STM32H7 or ESP32? No. The Go engine needs Linux. The STM32MP25 and ctrlX CORE are MPU-class boards that run Linux, which is why they work; the STM32H7, STM32L4 and ESP32 are bare-metal Cortex-M parts and are not supported by the engine today. Bare-metal MCU support is on ForestHub’s roadmap.

Q: What language is the runtime written in? Go (the execution engine, LLM proxy, hardware drivers, MQTT) plus TypeScript (the workflow-core, visual builder, and CLI). There is no C / C++ / Rust / Python in the runtime — and it does not generate Cortex-M firmware.

Q: What license is it? Dual-licensed: Apache-2.0 for the core (contract/ OpenAPI spec and ts/workflow-core), and AGPL-3.0 / commercial for the engine, builder, and CLI.

Q: How big is it? The engine binary is about 30 MB. It is offline by default — no cloud dependency unless you wire in a remote LLM node.

Related pages

• edge-agents Hardware Support (MPU vs MCU)
• fh-workflow CLI Reference
• STM32 Agent
• MCU Agent Architecture
• Best MCU Agent Tools