Edgelet

Upstream: eclipse-iofog/edgelet · Datasance distribution: Datasance/edgelet

Lightweight container runtime for far-edge devices and ioFog/PoT node agent.

Edgelet is a single edgelet binary per platform. On Linux it ships a thin CLI wrapper with an embedded container runtime. On macOS and Windows it runs as a monolithic binary against an external Docker or Podman engine. The daemon manages microservice workloads, syncs with the Controller, and exposes the on-device EdgeletAPI for local administration.

Documentation: docs/edgelet/README.md

Platforms

Platform	Binary model	Container engine	Role in beta
Linux (amd64, arm64, arm, riscv64)	Thin wrapper (~31 MiB) + embedded fat runtime	edgelet (default), docker, podman	Production far-edge / device-edge node agent
macOS (amd64, arm64)	Monolithic ELF	docker, podman only — Docker Desktop, Podman Machine, or OrbStack	Supported development platform (not a production edge node OS)
Windows (amd64)	Monolithic .exe	docker, podman only	Tier 2 — CLI and cross-compile verified; no Windows integration-test matrix

Linux thin binary installs to /usr/local/bin/edgelet, lazy-extracts the fat runtime to /var/lib/edgelet/data/current/, and starts the daemon with edgelet daemon or systemctl start edgelet. Desktop platforms do not embed a runtime; point containerEngineUrl at your local engine socket.

macOS development

Use an external engine and the desktop monolithic build:

make install-dev start-dev
export SNAP_COMMON=$(pwd)/dev
edgelet system status
edgelet system info

Stop and inspect logs:

make stop-dev
tail -f dev/var/log/edgelet/daemon-startup.log

CLI reference: docs/cli/README.md · output schemas · CLI migration from legacy ioFog Agent

Project structure

.
├── cmd/edgelet/             # Multicall entry (CLI, daemon, containerd child)
├── internal/
│   ├── auth/                # TLS / JWT / EdgeletAPI PKI
│   ├── edgeletapi/          # EdgeletAPI HTTP/WebSocket (:54321)
│   ├── fieldagent/          # Controller communication
│   ├── processmanager/      # Container reconciliation
│   ├── store/               # SQLite persistence
│   └── supervisor/          # Module orchestration
├── pkg/
│   ├── containerd/          # In-process containerd (edgelet engine)
│   └── engine/              # ContainerEngine + docker/podman/edgelet adapters
├── install.sh               # Binary installer (multi-OS)
├── uninstall.sh             # Clean uninstaller
├── packaging/               # systemd unit, config templates
└── docs/edgelet/            # Operator documentation

Prerequisites

Tool	Version	Notes
Go	1.26.4+	See go.mod
Make	any	GNU Make
Docker	26.10+	Required for macOS release builds and embed CI
Docker / Podman	26.10+	When containerEngine is docker or podman
golangci-lint	v2.12.2	Auto-installed by make lint

On Linux native embed builds, install cross-compilers:

sudo apt-get install -y \
  gcc gcc-aarch64-linux-gnu gcc-arm-linux-gnueabihf gcc-riscv64-linux-gnu \
  musl-tools musl-dev

Container engine

Runtime selection via containerEngine in config (validated per GOOS):

Platform	Allowed containerEngine	Default
linux	edgelet, docker, podman	edgelet
darwin / windows	docker, podman	docker

profiles:
  production:
    containerEngine: edgelet
    containerEngineUrl: unix:///run/edgelet/containerd.sock
    pruningFrequency: 24
    watchdogEnabled: true

Details: docs/edgelet/container-engine.md

Building

macOS (release matrix): use the Docker embed loop — do not use make build-all-archs (requires native Linux cross-toolchains):

./test/release/build-all.sh    # all 7 release binaries
make build-release-matrix      # alias for build-all.sh

After changing embed build dependencies, refresh CI images:

RELEASE_FRESH_CI_IMAGE=1 ./test/release/build-all.sh

Linux: ./test/release/build-all.sh or make build-all-archs, plus desktop targets:

make build-desktop-darwin build-desktop-windows
scripts/release-binaries.sh v1.0.0-rc.1

Local / single-target builds:

make build                    # host OS: linux thin or desktop monolithic
make build-edgelet-linux      # unified linux thin (ARCH=amd64 default)
make deps                     # embed pipeline before linux thin build
make build-linux-amd64        # deps + thin for amd64
make build-linux-arm64        # deps + thin for arm64
make build-desktop-darwin     # darwin monolithic
make release-binaries VERSION=v1.0.0-rc.1

Testing

make test
make test-unit
make test-coverage

Embedded-engine integration (Lima VM on macOS): test/embedded/README.md

Quality gates before contributing:

make lint
make security-code
make vulncheck
make fmt

Installation

Binary-only releases (no DEB/RPM, no release .tar.gz bundles). Default Linux engine: edgelet.

Channel	GitHub repo	Container image
Eclipse (canonical)	eclipse-iofog/edgelet	ghcr.io/eclipse-iofog/edgelet:<tag>
Datasance mirror	Datasance/edgelet	ghcr.io/datasance/edgelet:<tag>

Identical builds and tags; choose the channel that matches your fleet docs. Override install source at runtime with EDGELET_GITHUB_REPO.

Eclipse (canonical)

curl -fsSL https://github.com/eclipse-iofog/edgelet/releases/download/v1.0.0-rc.1/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh --version=v1.0.0-rc.1
# dev / CI: sudo ./install.sh --bin-path=build/edgelet-linux-amd64 --version=dev

Datasance mirror

curl -fsSL https://github.com/Datasance/edgelet/releases/download/v1.0.0-rc.1/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh --version=v1.0.0-rc.1

Release artifacts per tag: seven binaries (edgelet-linux-<arch>, edgelet-darwin-<arch>, edgelet-windows-amd64.exe), SHA256SUMS, install.sh, uninstall.sh, and config/CA samples.

Install paths

Purpose	Linux	macOS	Windows
Binary	/usr/local/bin/edgelet	/usr/local/bin/edgelet	%ProgramFiles%\Edgelet\edgelet.exe
Config	/etc/edgelet/config.yaml	/etc/edgelet/config.yaml	%ProgramData%\Edgelet\config\config.yaml
Data	/var/lib/edgelet/	/var/lib/edgelet/	%ProgramData%\Edgelet\data\
Runtime	/run/edgelet/	/var/run/edgelet/	%ProgramData%\Edgelet\run\
Logs	/var/log/edgelet/	/var/log/edgelet/	%ProgramData%\Edgelet\log\
Scripts	/usr/share/edgelet/	/usr/local/share/edgelet/	%ProgramData%\Edgelet\scripts\

sudo edgelet init-config                     # default config if missing
edgelet daemon                               # foreground
systemctl start edgelet                      # production (linux)
edgelet config --a <iofog/pot controller-api-endpoint> # configure which controller edgelet is going to connect (post-install)
edgelet provision <key>                      # register with Controller (post-install)

Installation: docs/edgelet/installation.md · Deployment topology: docs/edgelet/deployment.md

Local IT container tag: edgelet:local (EDGELET_IMAGE=edgelet:local).

Uninstall

sudo sh uninstall.sh
sudo sh uninstall.sh --remove-data

EdgeletAPI

On-device operator API (daemon↔CLI):

Item	Value
HTTPS	https://127.0.0.1:54321
Routes	/v1/...
CLI token	/etc/edgelet/edgelet-api
TLS CA	/etc/edgelet/edgeletapi-ca.crt

Guide: docs/edgelet/edgelet-api-v1.md · OpenAPI: docs/edgelet/edgelet-api-v1-openapi.yaml

Controller REST (field agent) uses /api/v3/... on the controller URL — separate from EdgeletAPI.

CI

Workflow	Purpose
.github/workflows/ci.yml	Build, lint, unit tests
.github/workflows/govulncheck.yml	Dependency vulnerability scan
.github/workflows/release.yml	Release matrix on tag push

Contributing

See CONTRIBUTING.md.

License

EPL-2.0