KubeSolo is a single-node, ultra-lightweight, OCI-compliant Kubernetes distribution. It removes all multi-node clustering logic from Kubernetes (no etcd quorum, no leader election, no control plane spreading across machines), leaving you with a full Kubernetes runtime that runs on a single node in under 200MB RAM.

How is KubeSolo different from K3s?

Both KubeSolo and K3s are lightweight Kubernetes distributions. KubeSolo is optimized specifically for single-node deployments and removes clustering support entirely rather than making it optional. This results in a smaller RAM footprint and simpler operational model. KubeSolo is also specifically optimized for flash storage (common in IoT and edge hardware), where K3s makes fewer assumptions about the storage layer.

Can I run KubeSolo instead of Docker?

Yes. KubeSolo is OCI-compliant, so any container image that runs on Docker or Podman runs on KubeSolo. You gain the full Kubernetes API (declarative lifecycle management, RBAC, Helm, CRDs, and ecosystem tooling) on hardware you were previously running Docker on. Tools like Kompose can convert existing docker-compose.yaml files to Kubernetes manifests, and with d2k enabled KubeSolo also exposes a Docker-compatible API, so existing Docker CLI commands and scripts can target the node.

What hardware does KubeSolo run on?

KubeSolo runs on any Linux system with ARM, ARM64, x86_64, or RISC-V 64 architecture and at least 200MB of available RAM. It is specifically optimized for constrained hardware including embedded devices, industrial gateways, Raspberry Pis, and systems with flash storage like CFlash cards.

Is KubeSolo open source?

Yes. KubeSolo is open source, developed and maintained by Portainer.io Limited. Source is available on GitHub.

How does KubeSolo relate to Portainer?

KubeSolo is a Portainer product. Portainer's Edge Agent integrates with KubeSolo to provide a fleet management layer: centralized GitOps deployments, RBAC, and lifecycle management across multiple KubeSolo nodes from a single control plane. KubeSolo works standalone without Portainer; Portainer is an optional addition for teams managing multiple nodes.

open source · MIT · by portainer

Kubernetes for everywhere
you run containers.

Name: KubeSolo
Author: Portainer.io Limited

Anywhere you've been running Docker or Podman, you can now run Kubernetes. KubeSolo strips out all the clustering machinery and gives you the full Kubernetes API on a single node… starting at under 200 MB RAM.

curl -sfL https://get.kubesolo.io | sudo sh -

Get started → Documentation GitHub

MEMORY

<200 MB

RAM at idle

PLATFORMS

4 arch

ARM · ARM64 · x86_64 · RISC-V 64

OVERHEAD

Zero

Cluster overhead

API STATUS

Full K8s

API compatible

What is KubeSolo?

Single-node Kubernetes with the clustering machinery removed. Not disabled. Removed.

Most Kubernetes distributions are built for multi-node clusters and then adapted for smaller deployments. KubeSolo starts from the opposite direction. It takes Kubernetes and removes everything that only makes sense when there's more than one node: etcd quorum logic, leader election, multi-node networking overlays, control plane distribution. None of it is present.

What remains is a full Kubernetes control loop on a single process. The API server, controller manager, kubelet, and kube-proxy all run together, and a lightweight webhook assigns pods to the node in place of the scheduler. Your existing manifests, Helm charts, and CRDs work without modification.

The design target is anywhere you would have previously reached for Docker or Podman: edge devices, factory hardware, developer laptops, remote sites, IoT gateways, kiosk machines. Anywhere a single-node runtime makes sense and a full cluster is overhead you don't need.

KubeSolo is open source (MIT) and maintained by Portainer.

kubesolo install

1# install KubeSolo

2curl -sfL https://get.kubesolo.io | sudo sh -

4🔍 Detected glibc system

5🔍 Detected init system: systemd

6📥 Downloading kubesolo v1.2.1...

7✅ Configuration written to /etc/kubesolo/config.yaml

8✅ kubesolo service created and started with systemd

9✅ kubesolo installation completed!

11$ kubectl get nodes

12NAME STATUS ROLES AGE VERSION

13rpi-gate Ready <none> 8s v1.35.7+kubesolo-v1.2.1

15$ kubectl apply -f mosquitto.yaml

16namespace/mosquitto created

When does KubeSolo make sense?

Anywhere a single node is the right unit of deployment and multi-node cluster complexity is overhead you'd never use.

Device edge & far edge

Industrial gateways, sensor aggregators, remote monitoring nodes. Full Kubernetes where connectivity is intermittent and RAM is measured in megabytes.

edge

Factory floors & OT

Air-gapped industrial infrastructure running ISA-95 workloads. The offline build embeds KubeSolo's own system images, so it installs and runs with no cloud connectivity. Point registry mirrors at an internal registry for your own images.

air-gapped

IoT & embedded systems

Raspberry Pis, ARM SBCs, embedded Linux devices that were previously running Docker Compose. Upgrade the runtime without upgrading the hardware.

arm64

Developer workstations

Local Kubernetes that doesn't need a hypervisor or eat your laptop's memory. Write manifests locally, deploy identically to production. On Linux it runs natively with no Docker Desktop required; on macOS and Windows (WSL2), kubesoloctl runs it in a container on Docker.

local dev

Remote & branch sites

Small offices, retail locations, field deployments. One KubeSolo node per site with the same operational model as the rest of your fleet.

fleet

Kiosk & appliance workloads

Interactive terminals, digital signage, point-of-sale systems. Lifecycle-managed container workloads on locked-down purpose-built hardware.

embedded

KubeSolo vs Docker / Podman

If you're running Docker today because Kubernetes felt like too much for a single node, KubeSolo is the upgrade that changes that calculus.

Docker / Podman

RUNTIME ONLY

✗No declarative desired-state management

✗No built-in RBAC or multi-tenant access control

✗No Helm or CRD support

✗No native health management or automatic restarts beyond basic flags

✗No standard ecosystem tooling (operators, service mesh, GitOps)

✗Compose files don't translate to production K8s deployments

✗Adopting Kubernetes means retooling every Docker script and CI job

KubeSolo

FULL K8S API

✓Declarative workload management via standard manifests

✓Full RBAC, ServiceAccounts, and namespace isolation

✓Helm and CRD support out of the box

✓Native liveness/readiness probes, restart policies, resource limits

✓Full ecosystem compatibility: operators, Flux, ArgoCD, Prometheus

✓Same OCI images, no changes to your existing container builds

✓Keep the Docker CLI: d2k exposes a Docker-compatible API over mTLS that translates to Kubernetes

What ships in the binary

The things edge fleets end up needing, already built in. Each is a setting in one config file, not another add-on to install.

Declarative configuration

Every setting lives in /etc/kubesolo/config.yaml. Change it with kubesoloctl config set, validate before saving, or manage it over a local socket API. Configuration →

config.yaml

Prometheus metrics

A built-in endpoint reports component health, certificate expiry and database size. Ready-made Grafana dashboards cover the API server, kubelet and containers. Observability →

:9105/metrics

Docker API compatibility

d2k exposes a Docker-compatible API over mTLS, so docker ps, existing scripts and CI jobs can target a KubeSolo node unchanged. d2k →

d2k

CPU pinning

The static CPU manager policy gives latency-sensitive pods exclusive cores, for motion control, audio and machine vision. CPU pinning →

real-time

Registry mirrors

Point image pulls at a mirror, a Harbor proxy cache or one internal registry for an air-gapped site, with private CAs and credentials. Registries →

air-gapped

kubesoloctl

One CLI to install, upgrade, reset and uninstall, plus a container mode that runs KubeSolo on macOS and Windows WSL2 for development. kubesoloctl →

cli

How KubeSolo compares to other lightweight Kubernetes distributions

K3s and MicroK8s are legitimate options. The differences come down to design priorities and what each one is optimized for.

Capability	KubeSolo	K3s	MicroK8s	Docker / Podman
Full Kubernetes API	✓	✓	✓	✗
RAM footprint <200 MB	✓	~	✗	✓
Single-node design (no cluster overhead)	✓	~	~	✓
ARM, ARM64, x86_64 & RISC-V 64	✓	✓	✓	✓
Flash / constrained storage optimized	✓	~	✗	~
Helm & CRD support	✓	✓	✓	✗
No etcd / no quorum	✓	✓	✗	✓
Air-gapped install	✓	✓	~	✓
OCI image compatible	✓	✓	✓	✓

Have questions?

The full FAQ covers everything from hardware requirements and CNCF certification to KubeEdge comparisons and multi-cluster management.

Read the full FAQ →

Get started in under 60 seconds

One command on Linux. kubesoloctl for macOS and Windows (WSL2).

Install

Run the install script with sudo on a Linux host. It installs the KubeSolo binary, writes /etc/kubesolo/config.yaml and starts KubeSolo under your init system (systemd, OpenRC, SysV, s6, runit or upstart). The installer stops if Docker is present; remove it first, or use kubesoloctl container mode on a development machine.

BASH
1$ curl -sfL https://get.kubesolo.io | sudo sh -

On macOS or Windows (WSL2), download kubesoloctl and run KubeSolo in a container on Docker:

BASH
1$ kubesoloctl install --run-mode=container

Set up kubectl

If kubectl is on the node, the installer merges the admin kubeconfig into ~/.kube/config for you, and so does kubesoloctl. To use kubectl from another machine, copy /var/lib/kubesolo/pki/admin/admin.kubeconfig to it, then set the context:

BASH
1$ kubectl config use-context kubernetes-admin@kubesolo
2$ kubectl get nodes
3# You should see a single node in Ready state

Deploy your first workload

Try the Mosquitto example from the KubeSolo repository:

BASH
1$ kubectl apply -f https://raw.githubusercontent.com/portainer/kubesolo/develop/examples/mosquitto.yaml
2$ kubectl get all -n mosquitto

Full install guide → Configuration reference

Managing multiple nodes? Add Portainer.

KubeSolo is a Portainer project. Portainer's Edge Agent connects your KubeSolo fleet into a single operator control plane: GitOps deployments, RBAC, and remote lifecycle management across every node without touching each one.

Explore Portainer →

Kubernetes for everywhereyou run containers.