Nanocl: a Rust orchestrator for containers and VMs that skips the Kubernetes control plane

What Nanocl replaces, and for whom

Nanocl targets platform engineers who need multi-service deployments without operating a full Kubernetes distribution. The README puts it plainly: it is "not a Kubernetes clone", lean where K8s is heavy and expressive where docker-compose is limiting. The problem it addresses is the gap between a local compose file and a production deployment: ad-hoc scripts, CORS workarounds and compose sprawl that grows as services multiply. The pitch is dev-to-prod symmetry, where the same declarative Statefile stays identical across environments.

The scope is wider than containers. Statefiles cover cargoes (containers), resources, jobs and virtual machines, and the repository ships examples for cron jobs, database replication, HTTP/3, secrets, TLS and port bindings. That breadth is the reason to look at it: one model for a container, a scheduled job and a VM, rather than three tools. It is also the reason to be careful. The README describes Nanocl as evolving fast and asks early adopters to shape the roadmap, which is an honest signal about the stability of the surface area.

The daemon, the store, and the optional data planes

The architecture is a set of modular containerized services. nstore persists cluster state. ndaemon exposes the REST API and control surface. nmetrics collects resource usage. ncproxy is a proxy controller with an embedded nginx data plane, and ncdns is a DNS controller with an embedded dnsmasq data plane. Both proxy and DNS are marked optional in the README, so a minimal install is the store, the daemon and metrics.

The repository confirms the split at the crate level. The Cargo workspace has members under bin/ for ncproxy, ncdns, ncvpnkit, nanocld and nanocl, plus shared crates for errors, stubs, utilities and a daemon client. That layout matters when you evaluate the project: the CLI is a client of the daemon, not a standalone tool, and the proxy and DNS services are separate binaries that can be deployed or left out.

The docker-compose.yaml used for development shows how the pieces fit. nstore runs as CockroachDB (docker.io/cockroachdb/cockroach:v25.4.13) on a bridge network named nanoclbr0, listening on 26257 and 26258, and it is labelled as a cargo with io.nanocl.kind=cargo and io.nanocl.c=system.nstore. Those labels are the orchestrator's own metadata applied to its own components, which is a neat demonstration that Nanocl manages itself with the same primitives it exposes to users.

Installing Nanocl and applying a first Statefile

The README gives a quick install that requires Docker, and points to a separate installation guide for Linux, macOS and Windows. The script is fetched and piped to sh:

curl -fsSL https://download.next-hat.com/scripts/get-nanocl.sh | sh

After that, the README says to complete the required post-installation steps before using the CLI. Those steps are linked from the README rather than reproduced in it, so read them before assuming the daemon is reachable.

The first real use is a Statefile. This is the minimal example from the README, with an ApiVersion, one cargo and one container:

ApiVersion: v0.16
Cargoes:
  - Name: hello
    Containers:
      - Name: hello
        Image: ghcr.io/next-hat/documentation:0.16.0

Apply it and inspect the result. The README shows these three commands in sequence:

nanocl state apply -s ./state.yml
nanocl cargo ls
nanocl cargo logs global.hello

What you should see is the cargo listed by `nanocl cargo ls` and the container's output from `nanocl cargo logs`. Note the key format: cargoes and VMs use canonical keys in `{namespace}.{name}` order, so a cargo created without `--namespace` lands in `global` and is addressed as `global.hello`. 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, while creation commands still default to `global`. Removing the deployment uses the same file:

nanocl state rm -s ./state.yml

Resources extend the same file. The README's own documentation deployment adds an ncproxy rule that maps a domain to a container port, which is how routing is expressed without a separate ingress manifest.

Where Nanocl is the wrong tool

The README's strongest warning is in the project's own voice: you could rebuild a Kubernetes inside Nanocl, but you probably will not want to. That is a boundary, not marketing. If your organisation already runs a Kubernetes distribution with an operator ecosystem, admission policies and a large hiring pool, Nanocl asks you to give that up for a smaller control plane and a smaller community. The README points to a Discord server and a roadmap rather than a catalogue of third-party integrations.

The lifecycle story is thinner than the feature list. The README links to health-check documentation for rolling update readiness and to TLS secret documentation for certificate persistence, which tells you those behaviours are documented externally and are not default guarantees you can infer from a Statefile. Rollback is the clearer gap: the documented operations are `nanocl state apply` and `nanocl state rm`. There is no rollback command in the README, and the README does not document rollback semantics. If your deployment process depends on reverting to a previous revision as a first-class operation, verify how you would do that before adopting.

There is also a version coupling to watch. The README's examples use `ApiVersion: v0.16` and images tagged 0.16.0, while the latest news section announces Nanocl 0.18.0. The release notes for 0.18.0 are linked from the README but not included in it, so the migration path between Statefile API versions is something to check in the release documents rather than assume.

Nanocl compared with Kubernetes and docker-compose

The closest comparison is Kubernetes, and the difference is architectural rather than cosmetic. Kubernetes ships a control plane with its own API server, scheduler, controller manager and etcd, and most users extend it with operators and CRDs. Nanocl keeps a smaller set: nstore for state, ndaemon for the REST API, nmetrics for usage, and optional ncproxy and ncdns with embedded nginx and dnsmasq data planes. Routing and DNS are part of the project rather than an add-on you install separately. That is fewer moving parts to operate and fewer places to configure, at the cost of the flexibility that comes from a pluggable ecosystem.

Against docker-compose the difference is in the target, not the syntax. Compose describes containers on one host and stops there; Nanocl describes cargoes, resources, jobs and virtual machines, and the same Statefile is meant to apply in development and production. Compose has no notion of a namespace key like `global.hello`, no job or cron primitive in the same file, and no VM in the same document. If your deployment is a handful of containers on one machine, Compose is simpler and Nanocl adds a daemon you have to run. If you are juggling compose files per environment plus scripts around them, that is the situation Nanocl is built for.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-05. Three component releases landed the same day: ncvpnkit 0.8.0, ncproxy 0.15.0 and ncdns 0.10.0. Those version numbers are worth reading together with the main project version, because the components move on their own cadence. A Nanocl install is therefore several independently versioned binaries, and an upgrade is not a single number you bump.

The workspace configuration suggests the maintainers care about release artefacts. The release profile sets opt-level = "z", lto = true, codegen-units = 1 and strip = true, which is the shape of a build tuned for small binaries rather than fast compile times. The default branch is nightly, not main, which is a detail to note if you plan to track the source rather than the installer.

On licensing, the repository contains both LICENSE-APACHE and LICENSE-MIT, and the project metadata lists Apache-2.0. That dual-file layout is common in Rust workspaces and usually means permissive terms, but the exact terms and how they interact with the components you deploy are worth reading in the licence files themselves. This is not legal advice; if the distinction matters for your distribution model, have someone read the files.

Editorial conclusion

Adopt Nanocl if you want a single declarative Statefile to describe containers, jobs and VMs and you are comfortable with a project whose README calls it evolving fast. Do not adopt it if you need a stable orchestration contract, a large ecosystem of operators, or documented rollback semantics; the README documents apply and remove, not rollback. Before committing, verify the post-installation steps on your target OS, the Statefile ApiVersion your installed build expects, and whether ncproxy and ncdns are part of your deployment or optional add-ons.

Frequently asked questions

Official sources

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