# Kairos: an immutable Linux base for edge Kubernetes

> Kairos combines an immutable Linux image, Kubernetes lifecycle management, A/B upgrades, and an optional P2P provisioning mesh. It is aimed at edge and bare-metal operators, but adopting the current monorepo release requires checking migration paths from its archived predecessor repositories.

**kairos-io/kairos** — The immutable Linux meta-distribution for edge Kubernetes.

- Repository: https://github.com/kairos-io/kairos
- Website: https://kairos.io
- Stars: 1,862 · Forks: 157
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/kairos-io-kairos

## Kairos targets the edge OS lifecycle

Kairos addresses a specific infrastructure problem: keeping distributed edge devices on a consistent operating-system and Kubernetes configuration. Conventional hosts can accumulate packages, configuration changes, and installation-specific state over time. Kairos instead treats the device image as the managed unit, with the README describing immutable, bootable Kubernetes and OS images built through a workflow comparable to writing a Dockerfile.

The intended users are engineers operating clusters on edge devices and bare metal, particularly teams that need to span regions or manage multiple nodes as one Kubernetes deployment. The project also targets organizations seeking to make operating-system changes traceable through image production and registry delivery rather than ad hoc modification on every device.

Kairos does not stop at generating an image. The README lists cluster creation, node provisioning, lifecycle management, and updating as supported activities. This distinction matters because an edge image is only useful if the platform can initialize it, connect nodes, and replace it later. Kairos packages those concerns into a Linux meta-distribution rather than presenting only a container image builder.

The repository is also intended to be distribution agnostic. According to the README, a cluster can use the Linux distribution of the operator's choice. That statement is broader than a single-board-computer image, although the repository topics include Raspberry Pi and bare-metal use. The documentation, rather than this summary, would need to establish which base distributions and device targets are supported for a particular deployment.

## One Go monorepo now carries the Kairos binaries

The current repository has been consolidated into one Go source tree with the module path `github.com/kairos-io/kairos/v4`. Runtime components, the SDK, and the image initializer share a root `go.mod` and ship under one release tag. This changes how an integrator must reason about versioning. A release of one absorbed component is no longer independent of the others.

The main executable is a multi-call binary stored under `cmd/kairos/`. It dispatches according to `argv[0]`, allowing the same binary to behave as `immucore`, `kairos-agent`, or `kcrypt-discovery-challenger`. Historical names are represented through symlinks. The Makefile describes `kairos-init` as the image initializer that installs this multi-call binary and those links into a base image.

Several responsibilities remain separate. `kcrypt-challenger` has a different dependency and lifecycle profile, so it ships as its own container image rather than joining the multi-call executable. The provider is embedded by `kairos-init` into standard images at `/system/providers/agent-provider-kairos`. The interactive installer is embedded at `/system/installer/kairos-installer` and is invoked through `kairos-agent interactive-install`.

The public Go SDK is imported as `github.com/kairos-io/kairos/v4/sdk`. For consumers not ready to deploy the combined executable, each absorbed directory retains a thin `main.go`. The README specifically states that `go build ./agent`, `go build ./immucore`, and `go build ./kcrypt/cmd/discovery` still produce standalone binaries from any commit. This offers a compatibility path, although it also means an integrator can accidentally retain a component-oriented deployment model while the project has moved toward unified releases.

## Image delivery, P2P coordination, and A/B upgrades

Kairos uses an image delivery model rather than asking operators to patch every node independently. The README states that a new image can be pushed to a container registry and that Kairos then performs secure, risk-free A/B atomic upgrades. The language describes the intended workflow, but this repository excerpt does not explain rollback commands, failure recovery steps, retention rules for the alternate partition, or behavior after a failed health check. Those operational details are not documented in the repository text.

The optional P2P mesh adds another path for node coordination. The README says it can automate bootstrapping and coordination and mentions a distributed ledger as part of that design. The provider package implements both an agent bus plugin and the command interface exposed through `kairos provider <cmd>`. Standard images receive the provider through the embedded path documented above.

This architecture divides responsibility between declarative images and runtime coordination. Images define the expected system configuration, while the optional mesh can help devices discover and coordinate with peers during bootstrap. The repository also contains a separate device-side discovery component and an in-cluster challenger server. However, the README excerpt does not define the wire protocol, trust model, network assumptions, ledger persistence, or recovery behavior. An evaluation should therefore distinguish the existence of these mechanisms from the operational guarantees required by a production network.

The approach is most relevant when node access is intermittent or administration occurs across many sites. It is less compelling for a small cluster with reliable centralized provisioning, especially if the existing workflow already handles immutable deployment effectively.

## First build starts at the Kairos build entrypoint

The README directs readers to the Kairos getting-started documentation for tutorials and examples.

For Go developers inspecting the monorepo, the Makefile provides a build entrypoint and documents a command that selects the `kairos` target:

```bash
make GOFLAGS='-race' kairos
```

This is the example shown in the Makefile for overriding Go build flags. It builds the project entrypoint rather than provisioning a device, and the resulting binary still requires the appropriate base image and Kairos configuration.

The repository also documents separate compatibility builds through `go build`:

```bash
go build ./agent
go build ./immucore
go build ./kcrypt/cmd/discovery
```

These commands produce the standalone binaries identified by the README. They are relevant to consumers retaining an older component model. New deployments should account for the monorepo's unified release tag before selecting between the multi-call binary and standalone builds.

A real first device use is to select a documented Kairos image, place it on a supported target, run the documented installation or provisioning procedure, and confirm Kubernetes startup. Without the target image and its configuration schema, those commands cannot be reproduced accurately.

## Monorepo migration raises the upgrade cost

The repository is not archived, and its last push was on 2026-10-15. The listed release history includes `v4.3.0` on 2026-09-08, following release candidates `v4.3.0-rc7` and `v4.3.0-rc6`. This supports treating the consolidated repository as the current location for development, but it does not eliminate migration work in existing automation.

The README says the former component repositories are archived while their tagged releases remain resolvable. Post-migration fixes land in the monorepo and ship on its release tag. Users must therefore decide whether their automation remains pinned to archived repository releases or moves to a Kairos monorepo ref. The supported ref choices named by the README are a commit SHA, `master`, or a Kairos release tag. A release tag offers the clearest fixed coordinate for repeatable automation, while `master` follows the branch tip.

GitHub Actions consumers face a separate rewrite. Absorbed workflows now live under `.github/workflows/`. The documented mapping changes references such as `kairos-io/kairos-factory-action/...` to `kairos-io/kairos/.github/workflows/reusable-factory.yaml`, with an equivalent change for linting. A dependency bot updating a package version will not correct this repository-path change automatically.

License obligations also follow the Apache-2.0 license, but the repository metadata alone is not enough for a compliance decision. Operators must inspect the full `LICENSE`, notices associated with distributed images and dependencies, and their own redistribution terms. This is a licensing identification, not legal advice.

## Kairos differs from a standard distro plus cluster installer

A practical alternative is to use a conventional Linux distribution and install Kubernetes and lifecycle tooling onto it. The difference is not simply the inclusion of a Kubernetes binary. The conventional route leaves more mutable host state and typically requires a separate image-building, configuration-management, and upgrade system. Kairos makes the immutable Linux image the lifecycle unit and adds mechanisms specific to distributed device operation, including A/B upgrades and optional P2P coordination.

Another alternative is a container-optimized immutable operating system with its own node provisioning solution. Kairos's distinction is its Kubernetes-focused meta-distribution model and its integrated collection of agent, immucore, discovery, provider, installer, and initializer components. It also supports distribution-agnostic intent. The exact operational differences from a specific competing operating system cannot be stated because no competitor is identified in the repository material, and making a feature comparison here would add unsupported claims.

Kairos is the wrong tool when an operator needs direct package mutation on each host as the normal administration model. It is also unsuitable when CI cannot produce and distribute bootable images, or when the organization cannot maintain A/B boot behavior. Its multi-call executable and shared release tag may also conflict with teams that require independently versioned agent, discovery, and SDK components.

The fit should be judged at the system boundary: image production, first boot, peer networking, Kubernetes startup, and future replacement of the OS image. Success in creating an image alone does not establish that Kairos suits the full node lifecycle.

## Conclusion

Edge platform teams should consider Kairos when immutable images, Kubernetes lifecycle operations, and controlled A/B upgrades are central requirements. It is a poor fit for operators that require a conventional writable Linux distribution or cannot accommodate the monorepo migration. Before adoption, verify that the selected v4 image, release tag, external workflows, and SDK imports satisfy the deployment pipeline, then confirm the supported base distribution and upgrade path in the Kairos documentation.

## FAQ

### What problem does Kairos solve for edge Kubernetes?

Kairos provides immutable, bootable Linux and Kubernetes images for edge devices and bare metal. Its lifecycle model also covers provisioning, cluster management, and A/B image upgrades.

### Can Kairos coordinate nodes over a P2P mesh?

The README describes an optional P2P mesh for automated node bootstrapping and coordination. The provider is embedded into standard images and is also exposed through `kairos provider <cmd>`.

### What changed for users of the old Kairos component repositories?

The device runtime, SDK, and image initializer now share one monorepo, `go.mod`, and release tag. Existing GitHub Actions references may need to move from archived repository paths to workflows under this repository's `.github/workflows/` directory.

## Sources

- [kairos-io/kairos on GitHub](https://github.com/kairos-io/kairos)
- [License: Apache-2.0](https://github.com/kairos-io/kairos/blob/master/LICENSE)
- [Project website](https://kairos.io)
- [README](https://github.com/kairos-io/kairos/blob/master/README.md)
- [Releases](https://github.com/kairos-io/kairos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kairos-io-kairos