Runtime Types

Introduction

AosCore supports three distinct runtime types, each designed for a different class of workload on a Node. The runtime type determines how a Deployable Item is executed, what level of isolation it receives, how it is updated, and what operational constraints apply.

When the cloud sends a desired state, each Instance is assigned to a specific runtime based on the Node's available runtimes and the Deployable Item's type. The Service Manager's Launcher module dispatches instance operations to the appropriate runtime. This page compares the three runtime types from an operational perspective — helping OEMs understand which runtime is appropriate for each workload category.

Runtime Types at a Glance

Characteristic	Container	Boot	Rootfs
Workload type	Application services	Boot-level firmware	System-level components
Isolation	Full (namespaces + cgroups)	None (bare partition)	None (host filesystem)
Concurrent instances	Multiple (unlimited)	1	1
Update mechanism	In-place restart	A/B partition swap + reboot	Image copy + reboot
Reboot required	No	Yes	Yes
Rollback strategy	Restart previous version	Boot from previous partition	Revert to previous rootfs
Resource limits	CPU, RAM, PID (cgroups)	Not applicable	Not applicable
Per-instance networking	Yes (CNI)	No	No
Per-instance monitoring	Yes (CPU, RAM, disk, network)	No	No
Image format	OCI container layers	Compressed partition image	Squashfs image
Item type	Service	Component	Component

Container Runtime

The container runtime is the primary execution environment for standard AosEdge application services. It provides full process isolation using Linux namespaces and resource control via cgroups.

Characteristics

• Isolation model — each instance runs in its own set of Linux namespaces (PID, network, mount, UTS, IPC). The container sees an isolated process tree, its own network stack, and a dedicated root filesystem.
• Resource enforcement — CPU quota/period, memory limits, and PID limits are enforced through cgroups. The Service Manager monitors actual resource consumption and generates alerts when thresholds are exceeded.
• Networking — each container instance receives a dedicated network namespace configured via CNI plugins. The Network Manager handles IP allocation, DNS configuration, and host entries.
• Storage — containers can have persistent state (/state.dat) preserved across restarts and persistent storage (/storage/) preserved across version updates.
• Execution — containers are managed as systemd transient units using an OCI-compatible runtime binary (e.g., crun). The Runner module handles unit lifecycle and status monitoring.
• Concurrency — a Node can run multiple container instances simultaneously, limited only by available resources.

Update Behavior

Container updates do not require a system reboot:

1. The Launcher stops the running instance (systemd unit stop → SIGKILL)
2. The new service image layers are prepared as an overlay filesystem
3. A new container instance starts with the updated image
4. The instance transitions through Activating → Active states

If the new version fails to start, the instance enters the Failed state and the cloud is notified. The previous version's image remains available for rollback via a new desired-state update.

Use Cases

• Application-level services (data processing, edge analytics, protocol adapters)
• Workloads requiring process isolation from other services and the host
• Services that need per-instance resource limits and monitoring
• Workloads with frequent update cycles (no reboot overhead)

Boot Runtime

The boot runtime manages firmware-level components that are deployed as complete boot partition images. It implements an A/B partition scheme for safe updates with automatic rollback on failure.

Characteristics

• Isolation model — none. The boot runtime manages what runs at the system boot level. The deployed image becomes the active boot partition for the entire Node.
• Partition scheme — two boot partitions (A/B) are maintained. At any time, one is active (currently booted) and one is available for updates. After a successful update, the partitions swap roles.
• Single instance — only one boot component can be managed per boot runtime. The runtime reports maxInstances: 1.
• EFI integration — the boot runtime uses EFI boot variables to control which partition the system boots from. It sets boot-success flags and manages boot order.
• Health verification — after a reboot into the new partition, configured systemd services must reach active state. If health checks fail, the system reverts to the previous partition on the next reboot.

Update Behavior

Boot updates always require a system reboot:

1. The new image is written to the inactive partition
2. EFI boot variables are updated to boot from the new partition
3. The Launcher triggers a system reboot
4. After reboot, the boot runtime confirms successful boot (SetBootOK)
5. Health check services are monitored for active state
6. On success: the update is finalized and the inactive partition is synced as a backup
7. On failure: the system reverts to the previous partition

The A/B scheme ensures that a failed update never leaves the system unbootable — the previous known-good partition is always available as a fallback.

Use Cases

• Bootloader or kernel updates
• Low-level firmware components that must be present at boot time
• System images where the entire boot partition must be atomically replaced
• Components where rollback must be guaranteed at the hardware/EFI level

Rootfs Runtime

The rootfs runtime manages system-level components deployed as squashfs filesystem images. Like the boot runtime, it requires reboots for updates, but operates on the root filesystem rather than boot partitions.

Characteristics

• Isolation model — none. The rootfs component becomes part of the system's root filesystem after the update is applied during boot.
• Image format — components are packaged as squashfs images (.squashfs). Both full replacement and incremental (delta) updates are supported.
• Single instance — only one rootfs component can be managed per rootfs runtime. The runtime reports maxInstances: 1.
• Action-based state machine — the rootfs runtime uses action files (do_update, updated, do_apply, failed) to coordinate the multi-reboot update process with external boot scripts.
• Health verification — after the rootfs image is applied and the system reboots, configured systemd services must reach active state. Failure triggers a rollback to the previous rootfs.

Update Behavior

Rootfs updates require one or two system reboots:

1. The squashfs image is extracted from the OCI layer to the working directory
2. An action file (do_update) is written indicating the update type (full or incremental)
3. The pending instance state is saved
4. The Launcher triggers a system reboot
5. During boot, external scripts detect the do_update action and apply the image
6. After boot, the rootfs runtime reads the resulting state:
   • If updated: health checks run. On success, a do_apply action is written and another reboot is requested to finalize. On failure, a failed action is written.
   • If failed: the update is marked as failed, artifacts are cleaned up, and the previous version remains active.
   • If no action (final boot): the pending instance is promoted to installed, success is reported.

Image Types

Type	Media Type Prefix	Description
Full	vnd.aos.image.component.full	Complete filesystem image — replaces the entire rootfs
Incremental	vnd.aos.image.component.inc	Delta update — applied on top of the existing rootfs

Use Cases

• Operating system or distribution updates
• System libraries and middleware that are part of the root filesystem
• Components that need atomic filesystem-level replacement
• Scenarios where incremental (delta) updates reduce download size

Choosing the Right Runtime

The runtime selection depends on the nature of the workload:

Decision Factor	Container	Boot	Rootfs
Needs process isolation?	✓	—	—
Needs per-instance resource limits?	✓	—	—
Needs per-instance networking?	✓	—	—
Can tolerate reboots for updates?	—	✓	✓
Must be present at boot time?	—	✓	—
Is a system-level component?	—	—	✓
Needs A/B partition rollback?	—	✓	—
Supports multiple concurrent instances?	✓	—	—
Supports incremental (delta) updates?	—	—	✓

In a typical AosEdge deployment:

• Application services (the majority of workloads) use the container runtime
• Firmware and bootloader components use the boot runtime
• OS-level system components use the rootfs runtime

A single Node can have all three runtimes configured simultaneously. The Launcher dispatches each instance to the correct runtime based on the runtime ID assigned by the cloud during scheduling.

Runtime Registration and Discovery

Each configured runtime reports its capabilities to the Communication Manager during SM registration. This information enables the cloud to make informed scheduling decisions:

• Runtime ID — unique identifier for the runtime instance on this Node
• Runtime type — the configured type string (e.g., "crun", "boot", "rootfs")
• Architecture — CPU architecture (e.g., aarch64, x86_64)
• OS — operating system (e.g., linux)
• Max instances — maximum concurrent instances the runtime supports
• DMIPS — processing capability metric
• RAM — available memory

The cloud uses this information to determine which Nodes can run a given Deployable Item and to balance workloads across available runtimes.

Related Pages

• Launcher — implementation details of the Launcher module and runtime plugin architecture
• Service Instance States — state machine for instance lifecycle transitions

• Image Deployment Pipeline — how OCI images are downloaded and prepared before runtime execution

• Scheduling and Placement — how CM assigns instances to runtimes based on capabilities

• Deployment Flows — the broader update flow including SOTA and FOTA

• Key Concepts — definitions of Deployable Item, Instance, and Verification