openBalena: Self-Hosted IoT Fleet Management with balenaOS and Container Updates

What openBalena Manages and Who Uses It

openBalena manages fleets of devices running balenaOS, a minimal host operating system built for running containers on embedded and IoT hardware. The README describes it as the open-source version of balenaCloud, sharing the same core technology and backend services that balena has run in production on balenaCloud for years.

The management workflow centers on the balena CLI. Engineers use it to configure application containers, push software updates to the fleet, check device status, view logs, and access devices remotely. The README describes the target use case as any deployment where connected devices need to receive container updates reliably, whether one device or a large fleet.

The backend is composed of five services: the API for device information and management, the VPN for remote access regardless of the device's network environment, the Registry for storing and distributing container images, an S3-compatible storage service, and the Database. These are all composed together in the docker-compose.yml file in the repository.

The Architecture: Five Backend Services in Docker Compose

The docker-compose.yml in the repository defines the full set of backend services openBalena requires. The services include: open-balena-api, open-balena-vpn, the container registry, an S3-compatible object storage service, and a PostgreSQL-based database (the internal name in the compose file is still resin, a legacy name from balena's earlier product name).

Each service uses a standard restart policy and health checks. The compose file uses YAML anchors to share common environment variables across services, including DB_NAME, DB_PASSWORD, DB_USER, LOG_LEVEL, and PRODUCTION_MODE. Several services require elevated Linux capabilities (SYS_ADMIN, SYS_RESOURCE) and network privileges (NET_ADMIN) for VPN and container management operations.

The minimum version requirements for a working deployment are balenaOS v5.2.8 and balena CLI v18.2.2. The README notes that in-place upgrades may succeed but recommends deploying a new instance in parallel when performing major updates, copying state across, and pointing a test device to the new instance before switching production traffic.

Configuring and Starting an openBalena Instance

The repository provides a Makefile that covers the main operational commands. Setting up the environment writes all supported variables to a .env file:

make config

The DNS_TLD variable is required and has no default. The SUPERUSER_EMAIL defaults to admin@$(DNS_TLD). Other variables include ACME_EMAIL for TLS certificate automation and CLOUDFLARE_API_TOKEN or GANDI_API_TOKEN for DNS-based ACME challenges (these two cannot be set simultaneously). After configuration, the health of the installation can be verified with:

make verify

This runs curl against the public API endpoint at https://api.$(DNS_TLD)/ping with retry logic. The Makefile also provides a lint target for shell script validation using shellcheck. A Deploy to balena Cloud button is present in the README as an alternative path for those who prefer a hosted test environment before committing to a self-hosted deployment.

Key Differences Between openBalena and balenaCloud

The README provides an explicit comparison table. openBalena is single-user where balenaCloud supports multiple users and organizations. openBalena has no web-based dashboard; balenaCloud provides one. openBalena does not support binary container delta updates, which reduce the payload size when pushing incremental changes to devices; balenaCloud does.

A practical documentation gap is also noted: the dedicated openBalena documentation is still incomplete. The README directs users to the balenaCloud documentation for most reference material, with the explanation that the core concepts and functionality are identical. This means operators working with openBalena for the first time need to mentally map balenaCloud documentation to their self-hosted environment.

Security, maintenance, scaling, and reliability of the backend services are the operator's responsibility in an openBalena deployment. In balenaCloud these are handled by balena. The README states that openBalena is in beta and lacks several features before the maintainers would call it production-ready, including the full documentation, the full test suite, simplified deployment, remote host OS updates, and custom device type support.

openBalena vs. AWS IoT Greengrass

AWS IoT Greengrass is Amazon's edge management service that runs on IoT devices and connects them to AWS cloud services. It uses a different deployment model: Greengrass components are defined in a cloud-first pipeline tied to AWS IAM, AWS IoT Core, and the broader AWS ecosystem. This integration makes Greengrass a natural fit for teams already running workloads in AWS, but it also creates a hard dependency on AWS services for device management.

openBalena takes a different approach: it is self-contained and deployable on any Linux server without any cloud provider dependency. The management interface is the balena CLI rather than the AWS console or SDK. Devices connect to the self-hosted API and VPN rather than to AWS IoT Core endpoints.

For teams with existing AWS infrastructure and a need for tight cloud integration, Greengrass fits naturally. For teams that need to manage devices in air-gapped environments, avoid cloud provider lock-in, or run management infrastructure on their own hardware, openBalena addresses those constraints directly.

License and Release Cadence

openBalena is licensed under AGPL-3.0. The copyleft terms of AGPL-3.0 extend to network use: if you modify openBalena and run it as a service, those modifications must be made available to users of the service. Organizations considering customization and internal deployment should review this implication with their legal team before building on the platform.

The release cadence is high: the repository shows three releases on 2026-09-28 alone (v4.1.961, v4.1.962, v4.1.963) and a last push on 2026-09-25. The patch versions increment rapidly, reflecting the continuous-delivery approach balena uses for the shared balenaCloud and openBalena backend. There is no separate release channel for openBalena.

Editorial conclusion

Engineering teams who need to manage a fleet of IoT devices running containerized applications and want full control over the management infrastructure should evaluate openBalena. The README notes that openBalena is currently in beta and lacks features the maintainers consider necessary before calling it production-ready, including full documentation, a full test suite, simplified deployment, remote host OS updates, and support for custom device types. balenaCloud, the commercial hosted version, is the appropriate choice for teams that need a web dashboard, binary container delta updates, multi-user organizations, or production SLA guarantees. The platform is AGPL-3.0 licensed.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes