KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

hadron

★ 63 Open GitHub ↗

Hadron is a minimal, from-scratch Linux distro using vanilla components, engineered for trusted and flexible boot environments.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## Hadron Linux

**The foundational Linux distribution for the cloud and the edge.**

Hadron delivers a minimal, trustworthy operating system built from the ground up with vanilla upstream components. Engineered for security, flexibility, and reliability.

Hadron is Engineered by [Spectro Cloud](https://www.spectrocloud.com) from the [Kairos](https://kairos.io) team.

### Why Hadron?

- **Minimal & Lean**: Bare essentials only—no bloat, just what you need
- **Trusted Boot**: Secure boot environments with modern security standards
- **Upstream First**: Built with vanilla components, staying close to upstream
- **Edge & Cloud Ready**: Optimized for both cloud workloads and edge deployments
- **Seamless Updates**: A/B upgrade capabilities for zero-downtime operations

## Architecture

Hadron is a Linux Distribution built from scratch with a focus on minimalism and staying close to upstream sources:

- **Core Components**: Built on `musl` libc, `systemd` init system, and vanilla Linux kernels
- **Boot Methods**: Supports both Trusted Boot (via USI/UKI) and standard boot (via Dracut/GRUB)
- **Upgrade System**: Managed via Kairos agent for A/B style atomic upgrades
- **Upstream Alignment**: Minimal patches, maximum compatibility with upstream projects
- **Simple and no vendor-lock-in**: Hadron doesn't ship a package manager by default, and it's not based on any other Linux distribution. You can build packages on top of Hadron, or use the package manager you like.

## Development

To build locally the image, you just need to have Docker installed, clone the repository and run:

```
make build
```

To create an ISO, you can:

```
make devel-iso
```

And you can run it in a VM with:

```
make run-qemu
```

There is some args that you can pass to the make command to customize the build:
- `BOOTLOADER`: Choose between `grub` (default) or `systemd` for Trusted Boot
- `KERNEL_TYPE`: Choose between `default` or `cloud`. Cloud is a minimal kernel built for VM/cloud environments. Default is a more generic kernel with more drivers included.
- `KUBERNETES_DISTRO`: Choose between `k3s`, `k0s` or leave empty for no Kubernetes distribution
- `KUBERNETES_VERSION`: Specify the Kubernetes version to install (if `KUBERNETES_DISTRO` is set)
- `VERSION`: Specify the version tag for the built image (default is `latest`)
- `ARCH`: Specify the target architecture (default is `amd64`, choices are `amd64` or `arm64`)
- `FIPS`: Set to `fips` to build with FIPS support (default is `no-fips`)

### Building Kairos Images

**Note**: The following examples are for testing purposes only. The Dockerfile used for building Kairos images is automatically fetched from the [kairos repository](https://github.com/kairos-io/kairos) and should not be modified locally.

### Adding Custom CA Certificates

To add a custom CA certificate to a Hadron-based image, copy the certificate into `/usr/local/share/ca-certificates/` with a `.crt` extension and then run `update-ca-certificates`.

`/usr/local/share/ca-certificates/` is the recommended location for custom CAs. You do not need to edit `/etc/ca-certificates.conf` for certificates placed there. That file is only needed when enabling or disabling certificates shipped under `/usr/share/ca-certificates/`.

### Kernel Parameters (sysctl)

The full `sysctl(8)` CLI from procps-ng ships in Hadron-based images, so `sysctl --system`, `sysctl -w`, `sysctl -a`, and reading individual keys all work as expected (consumers such as Stylus rely on `sysctl --system` during preflight).

`sysctl` is included in the final/bootable image, not in the minimal Hadron container base image. systemd also ships `/usr/lib/systemd/systemd-sysctl`, but that tool only *applies* drop-in config files (`/etc/sysctl.d`, `/usr/lib/sysctl.d`, `/run/sysctl.d`) — it is [not a replacement](https://manpages.debian.org/testing/systemd/systemd-sysctl.service.8.en.html) for the `sysctl` command and cannot read, list, or set keys at runtime. Prefer the `sysctl` binary; `systemd-sysctl` is only a fallback for the `sysctl --system` apply step.

#### Building a Core Kairos Image

To build a core Kairos image (without Kubernetes distribution) based on Hadron:

```bash
# Pull the base Hadron image and build the Kairos image
make pull-image build-kairos BOOTLOADER=grub VERSION=v0.0.1

# Or for Trusted Boot:
make pull-image build-kairos BOOTLOADER=systemd VERSION=v0.0.1
```

This will:
- Fetch the latest Dockerfile from the kairos repository
- Build a core Kairos image named `hadron-init` based on the Hadron base image
- Use the specified bootloader (grub or systemd) and version

#### Building a Standard Image with Kubernetes

To build a standard image with a Kubernetes distribution (e.g., k3s or k0s):

```bash
# Build with k3s
make pull-image build-kairos BOOTLOADER=grub VERSION=v0.0.1 KUBERNETES_DISTRO=k3s

# Build with k0s
make pull-image build-kairos BOOTLOADER=grub VERSION=v0.0.1 KUBERNETES_DISTRO=k0s

# Optionally specify Kubernetes version
make pull-image build-kairos BOOTLOADER=grub VERSION=v0.0.1 KUBERNETES_DISTRO=k3s KUBERNETES_VERSION=v1.28.0
```

After building the Kairos image, you can create an ISO:

```bash
# For GRUB bootloader
make grub-iso

# For Trusted Boot
make trusted-iso
```

## License

Apache 2.0

## Acknowledgements

- https://github.com/firasuke/mussel For making things even easier than musl-cross-make with mussel. It was so plug-n-play that felt like a really nice experience right from the start.
- https://github.com/openembedded/openembedded-core/tree/master/meta/recipes-core/systemd which makes possible to build systemd on top of musl
- https://github.com/mocaccinoOS/mocaccino-micro For inspiration on how to build a musl system from scratch

hadron

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README