Edge Agent Quickstart: Run an Agent Workflow on a Raspberry Pi

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

This quickstart runs an AI agent workflow on a Raspberry Pi using the open-source edge-agents runtime — offline, end to end. You install the CLI, sketch a my.workflow.json, validate it, build the arm64 engine container, run it on the Pi on port 8081, and point it at a local llama.cpp model. Every command below is verbatim from the edge-agents repository.

The same steps apply to a Jetson Orin Nano, an x86 NUC, an STM32MP25 board or a ctrlX CORE — only the build platform differs. For the full device list see the hardware support matrix; for what the runtime is, see Open-Source Edge Agent Runtime.

Prerequisites

A Raspberry Pi 5 (8 GB) running 64-bit Linux, reachable over SSH.
Docker with buildx on your build host (your laptop or the Pi itself).
Node.js on the machine where you will edit workflows (for the CLI).
Optionally, a GGUF model file if you want a local LLM in the loop (step 5).

1. Install the CLI and Open the Builder

Install the CLI globally — no need to clone the repo — and open the visual builder on a workflow file:

# Install the CLI without cloning, then open the visual builder
npm i -g @foresthubai/workflow-cli
fh-workflow open my.workflow.json

The builder is a React Flow canvas. You place nodes and connect them with the five edge types described below.

2. Anatomy of a Workflow

A my.workflow.json is a directed graph. Nodes are steps; edges carry control and data. The five edge types are:

Edge type	Use it for
`control`	Plain step-to-step flow
`tool`	Invoking a capability / tool
`agentTask`	Handing work to an agent step
`agentChoice`	Letting an agent branch
`agentDelegate`	Delegating a sub-goal to another agent

A minimal edge workflow: a GPIO read node feeds an agentTask step (reason over the reading with an LLM), whose result flows over a control edge to an MQTT publish node. GPIO, UART, ADC, DAC and PWM are first-class nodes, and MQTT is a first-class transport, so this entire loop runs on the device. More patterns are on the workflow examples page.

3. Validate the Workflow

Before deploying, check the file structurally and then semantically:

fh-workflow check-schema my.workflow.json   # structural
fh-workflow validate my.workflow.json        # semantic

check-schema confirms the JSON matches the contract; validate checks that the graph makes sense (edges connect compatible nodes, no dangling references).

4. Build and Run the Engine on the Pi

The engine is a Go service. Build it for arm64, save the image, copy it to the Pi, and run it. It exposes its HTTP API on port 8081:

cd go
docker buildx build --platform linux/arm64 -t edge-agents/engine:arm64 --load .
docker save edge-agents/engine:arm64 -o engine.tar
docker run --rm -p 8081:8081 edge-agents/engine:arm64

Copy engine.tar to the Pi (scp engine.tar pi@raspberrypi:), docker load -i engine.tar there, then run the same docker run command on the Pi. The engine’s /deploy and /stop endpoints are gated by an ENGINE_SECRET — set it before exposing the engine on a shared network. Deployment is configured through env files: ENGINE_CONFIG_FILE (the workflow JSON), ENGINE_DEVICE_MANIFEST_FILE (/dev/… mappings), ENGINE_EXTERNAL_RESOURCES_FILE (MQTT brokers + LLM endpoints) and ENGINE_DEPLOYMENT_MAPPING_FILE (logical ID → resource bindings).

5. Point It at a Local LLM

To keep the agent fully offline, run a local llama.cpp server the engine can call. The image tag and model filename below are examples — pin or swap them for your build:

# image tag + model filename below are EXAMPLES — pin/replace as they drift
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

Then register http://localhost:8090 as the LLM endpoint in your ENGINE_EXTERNAL_RESOURCES_FILE. For choosing a model that fits your board, see Local LLMs for Edge Devices. You can also point the engine at a cloud LLM instead — local or cloud is a configuration choice, not a code change.

6. Optional: Generate a Workflow from Natural Language

If you would rather describe the workflow than draw it, the repo ships a Claude Code skill:

# NL -> workflow via the workflow-generate skill
npx skills add ForestHubAI/edge-agents --skill workflow-generate

Describe the sensor-to-action loop in plain language and it emits a my.workflow.json you can validate with step 3.

You’re Running an Edge Agent

At this point a workflow is executing on the Pi, reading hardware, reasoning with a local model, and acting — with no cloud round-trip. Browse the source on GitHub, check which other boards are supported in the hardware matrix, or, if you are taking this to production on an industrial fleet, book an architecture call with the ForestHub.ai team.

Open-Source Edge Agent Runtime — what edge-agents is
Edge Agent Hardware Support Matrix — supported devices
Edge Agent Workflow Examples — more sensor-to-action patterns
Local LLMs for Edge Devices — pick a model for your board

FAQ

Can I run this on a Jetson Orin Nano instead of a Pi? Yes. The only change is the build platform for the engine container. The CLI, workflow format and local-LLM steps are identical. See the hardware matrix.

Do I need an internet connection? No. With a local llama.cpp model (step 5), the whole loop runs offline. Cloud LLMs are optional.

What does the engine expose? An HTTP API on port 8081, with /deploy and /stop gated by ENGINE_SECRET. Deployment specifics come from the ENGINE_* env files described in step 4.

Where does the workflow format come from? It is defined by the project’s OpenAPI 3.0.3 contract and code-generated into the engine and tooling. See Open-Source Edge Agent Runtime for the contract-first design.