Nanocl: A Rust Orchestrator That Keeps Docker Compose Simplicity and Adds a Statefile

The Gap Nanocl Targets: Compose Scripts Versus a Full Kubernetes Distribution

Docker Compose handles a handful of services on one machine. Once you need a proxy rule, a TLS certificate, a DNS entry, a scheduled job, and a virtual machine alongside the containers, the compose file stops being the source of truth and the surrounding glue becomes a pile of scripts. Kubernetes solves that, but the README is explicit that Nanocl is not trying to be a Kubernetes clone. It states the project is for platform engineers who want isolation and predictable performance without the cognitive overhead of a full Kubernetes distribution, and it frames the scope as lean where K8s is heavy and expressive where docker-compose is limiting. The target user is therefore a small platform team, or a single engineer, running containers and virtual machines across a modest set of hosts who wants one declarative file rather than a control plane with its own upgrade cycle. The README also notes you could rebuild a K8s inside Nanocl but probably will not want to, which is a fair summary of the intended ceiling.

How the Statefile Drives Cargoes, Resources and Virtual Machines

The unit of configuration is a Statefile, written in YAML, TOML or JSON. The README gives a minimal example with ApiVersion v0.16, a Cargoes list, and inside it a container name and image. A Cargo is the abstraction over a workload: the README describes cargoes as containers, and virtual machines are declared in the same file with their own top-level section. Resources are the extension point. The documentation example defines a resource with Kind ncproxy.io/rule whose Data contains a Rules list with a Domain, a Network, and Locations mapping a Path to a Target with a Key and a Port. That key, global.doc.c, follows the canonical {namespace}.{name} form the README specifies, so the proxy rule points at a specific cargo instance in a specific namespace. The architecture table lists five services: nstore persists cluster state, ndaemon exposes the REST API and control surface, nmetrics collects resource usage, and ncproxy and ncdns are optional controllers with embedded nginx and dnsmasq data planes respectively. The control flow is therefore: CLI or API writes to nstore via ndaemon, controllers watch that state and reconcile the data planes. ncdns and ncproxy ship as separately versioned artifacts, which the release list confirms with ncdns-0.10.0 and ncproxy-0.15.0 tagged alongside ncvpnkit-0.8.0.

Getting It Running: Installer, Post-Install Steps and the Namespace Rules

The README's quick install is a single shell command, curl -fsSL https://download.next-hat.com/scripts/get-nanocl.sh | sh, and it states Docker is required. It then points to mandatory post-installation steps, which are not reproduced in the material available here, so that is the first thing to read in the linked guide before assuming the install is complete. Once running, the workflow is apply and inspect: nanocl state apply -s ./state.yml, then nanocl cargo ls, then nanocl cargo logs global.hello. Removal is nanocl state rm -s ./state.yml. The namespace behaviour is documented precisely and is worth reading twice. Cargoes and VMs use canonical keys in {namespace}.{name} order, so a listing shows entries such as global.hello or system.ncproxy. Collection commands return every namespace unless you pass --namespace, as in nanocl cargo ls --namespace system. Commands that target an existing cargo or VM take the key directly and do not accept a namespace option at all. Creation commands default to global when --namespace is omitted. That asymmetry between collection and targeting commands is a small thing that will bite anyone writing shell wrappers around the CLI.

Where the Documentation Is Thin and What That Costs You

The README is a landing page, not a reference. It points to separate documentation for health-check behaviour during rolling updates and for TLS certificate persistence, and it points to a daemon reference for the full set of object options. Nothing in the supplied material describes how nstore stores state, whether it is replicated, what happens to running cargoes when ndaemon restarts, or how a multi-node cluster is formed. The README describes Nanocl as a distributed system and lists nstore as the component that persists cluster state, but the mechanism for distributing that state is not given. The project also labels itself a work in progress, and the default branch is nightly, which is a meaningful signal about the stability of what you would be pulling. The ApiVersion in every README example is v0.16 while the latest linked release note is Nanocl 0.18.0, so the examples may lag the current schema. Treat the Statefile format as something to pin and test, not something to assume is frozen.

The Real Limitation: Optional Services Are Where the Operational Work Lives

The architecture table marks ncproxy and ncdns as optional, which is accurate but slightly misleading about effort. If you skip them, you have a scheduler with no ingress and no service discovery, and you are back to wiring a reverse proxy by hand. If you enable them, you are running an embedded nginx and an embedded dnsmasq under Nanocl's control, and those are the components that will generate the incidents, because DNS and TLS are what break first in any deployment. The README lists end-to-end TLS as a feature and notes that internal mesh primitives are in progress, so mesh networking is not a finished capability. Jobs and cron-style automation are listed as a feature, and backup and orphan cleanup tooling exists, but the material does not describe their guarantees. The honest framing is that Nanocl reduces the number of moving parts compared with a full Kubernetes distribution, not that it removes them. You still own DNS, certificates, and the upgrade path for three separately versioned services.

How It Differs From Kubernetes and From Compose

Against Kubernetes, the difference is architectural, not just ergonomic. Kubernetes defines a large API surface with custom resource definitions, controllers, admission webhooks, and a scheduler that operators extend. Nanocl defines a smaller set of first-class objects (cargoes, resources, jobs, virtual machines) and a resource abstraction layer the README describes as pluggable kinds, with ncproxy.io/rule as the worked example. That means fewer extension points but also fewer ways to get the control plane into a bad state. Against Docker Compose, the difference is that Compose stops at the container boundary. A Compose file cannot express a proxy rule, a DNS record, a cron job, or a virtual machine in the same document. Nanocl puts all of those in one Statefile with one apply and one remove. The trade is that you adopt a daemon, a state store, and at least two optional controllers, where Compose needs only the Docker engine you already have.

Maintenance, Versioning and the Apache-2.0 Licence

Nanocl is Apache-2.0, which permits commercial use, modification, and redistribution provided you keep the licence and notices, and it includes an express patent grant. That is a permissive licence with no copyleft obligation on your own code, and it is the same licence Kubernetes uses, so it should clear most corporate policy reviews. This is not legal advice; check with your own counsel if you plan to redistribute a modified daemon. On maintenance, the release cadence visible in the material is brisk: three component releases on the same day in September 2026 (ncvpnkit 0.8.0, ncproxy 0.15.0, ncdns 0.10.0), with ncdns still on a 0.x version. The README also carries a Hacktoberfest topic and an active release-notes trail through 0.14, 0.15, 0.16 and 0.18. Fast iteration on a nightly default branch means you should expect to read release notes before upgrading, and you should expect the Statefile ApiVersion to move. Pin your version, keep your Statefiles in git, and read the release note for the specific version you are moving to rather than the README, which trails behind.

Editorial conclusion

Nanocl fits platform engineers who want declarative container and VM orchestration on a small number of hosts without operating a Kubernetes control plane, and who are comfortable with a project that describes itself as a work in progress on the nightly branch. It is the wrong tool if you need a stable API surface, a large ecosystem of third-party operators, or multi-team tenancy with mature policy controls. Before adopting, verify the ApiVersion currently accepted by your installed daemon (the README shows v0.16 while the latest linked release note is 0.18.0), confirm the Statefile keys you depend on against the daemon reference, and check whether ncproxy and ncdns are stable enough for your ingress and DNS traffic.

Official sources

1. License: Apache-2.0
2. next-hat/nanocl on GitHub
3. Project website
4. README
5. Releases