embedded-agent.com

Embedded Agent Runtime Quickstart: Run an AI Agent on Pi 5, Jetson, STM32MP25 & ctrlX CORE

Last reviewed: 2026-06-04 · Marcus Rüb

Embedded Agent Runtime Quickstart

This is a hands-on walkthrough for deploying an embedded agent runtime onto Linux-class edge hardware — a Raspberry Pi 5, NVIDIA Jetson Orin Nano, STM32MP25, or Bosch Rexroth ctrlX CORE — using the open-source edge-agents runtime published by ForestHub.ai. Every command below is taken verbatim from the project README. Unlike a developer-laptop tutorial, the focus here is on-device deployment to the controller itself.

This page covers the on-device deployment path. For the developer-experience and CLI-centric angle — and the bare-metal MCU caveat in depth — see the sister hub mcuagent.com.

Prerequisites

edge-agents is a ~30 MB containerized runtime, so it fits comfortably alongside an existing Linux stack on these targets. Bare-metal microcontroller (Cortex-M) deployment is not a target of this runtime and is on the roadmap — do not attempt to flash this onto an MCU.

Step 1 — Author and validate a workflow

Workflows are plain data: a *.workflow.json file describing a graph of typed nodes. Install the CLI and visual builder, open a workflow, and validate it semantically before you ship it to a device.

# Visual builder + CLI
npm i -g @foresthubai/workflow-cli
fh-workflow open my.workflow.json      # Visual builder; Save writes to file
fh-workflow validate my.workflow.json  # Semantic validation

The validate step checks the graph against the OpenAPI 3.0.3 contract that is the runtime’s single source of truth, so a workflow that validates here will load on the engine.

Step 2 — Build and run the ARM64 engine on the controller

The engine ships as a container. On a Pi 5, Jetson, ctrlX CORE, or STM32MP25, build the ARM64 image and run it. The engine listens on port 8081.

# Engine on ARM64 (Pi / Jetson / ctrlX / STM32MP25)
cd go
docker buildx build --platform linux/arm64 -t edge-agents/engine:arm64 --load .
docker run --rm -p 8081:8081 edge-agents/engine:arm64

The engine now hosts your validated workflow as a running state machine on the device, executing locally with no cloud control plane required. If you cross-built the image on an x86 workstation, transfer it to the device (docker save / docker load or a local registry) before running.

Step 3 — Wire hardware I/O and MQTT nodes

The reason this is an embedded runtime and not a server framework is that hardware I/O is a first-class node type. GPIO, ADC/DAC/PWM, UART, and edge-trigger nodes map directly onto perception and action; an MQTT transport node handles device-to-device agent messaging. In your *.workflow.json, a GPIO read node feeds the reasoning nodes, and an MQTT publish node emits the result onto a topic that other agents or a supervisor subscribe to. This is the same layering described in the embedded agent architecture — the runtime just makes each layer a typed node you can draw.

Step 4 — (Optional) Generate a workflow from plain language

edge-agents ships a Claude Code skill that turns a natural-language description into a workflow graph. Add it with:

# Auto-generate a workflow from plain language (Claude Code skill)
npx skills add ForestHubAI/edge-agents --skill workflow-generate

Then validate the generated *.workflow.json with fh-workflow validate from Step 1 before deploying it.

Source and next steps

This tutorial is part of a ForestHub.ai knowledge hub. Deploying to your own controllers and want a second pair of eyes? Book a meeting →