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.

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, scheduler, controller manager, and kubelet all run together. 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[INFO] Detecting architecture... arm64

5[INFO] Downloading kubesolo v1.0.0

6[OK] Service started successfully

8# set kubeconfig context

9$ kubectl config use-context kubernetes-admin@kubesolo

10$ kubectl get nodes

11rpi-gate Ready <none> 8s v1.30.0

13$ kubectl apply -f mosquitto.yaml

14namespace/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. KubeSolo runs fully offline with no dependency on cloud connectivity or external registries.

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. No Docker Desktop required.

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

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

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. No prerequisites beyond a Linux system and curl.

Install

Run the install script with sudo. This installs the KubeSolo binary and starts the control plane as a systemd service. Ensure no existing container engine (Docker, Podman, containerd) is running first.

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

Set up kubectl

Copy the admin kubeconfig from /var/lib/kubesolo/pki/admin/admin.kubeconfig to the machine where kubectl is installed, 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.