Cupboard: provisioning local machines with the .NET SDK

A desired state framework written in the language you already deploy in

Cupboard is a framework for provisioning local environments to a desired state, using the .NET SDK, and it is distributed as a NuGet package named Cupboard.

The positioning needs stating plainly, because it is narrower than it sounds. This is not a configuration management server, it is not an agent and it does not talk to a fleet. It is a program you run, and that program brings the machine it runs on to a state you described in code. The word local in the description is doing real work.

That makes it a different kind of tool from the usual suspects in this space. A tool like a configuration manager is built around a long-lived agent that converges a machine towards a manifest over time, and its hard problems are scheduling, drift detection and partial failure. Cupboard has none of those problems, because it runs once, does a fixed list of things, and exits.

The trade is that a Cupboard program is a .NET program. The state you describe is described in C#, the same language and runtime as the applications you are probably provisioning for, and the build story is the .NET SDK rather than a separate agent and a separate configuration language.

The project is MIT licensed, carries a code of conduct, and the copyright notice reads Copyright (c) 2021 Patrik Svensson. The repository has no GitHub releases, and the last push was on 2026-05-25.

Three nouns: resources, manifests and catalogs

The whole model is three ideas, and the readme defines each of them tightly.

A resource describes the desired state for some part of a system. That might be a file, a directory, a package, and the readme uses the other examples too, a registry value and a script, once you look at the manifest further down. A resource is declarative, and the readme puts one sentence in bold about it: resources do not do anything when they are declared, they describe what will be done when executed.

A manifest contains one or many resources, and is used to specify how to assemble parts that use many resources. In practice a manifest is a class that overrides Execute and calls into a context object to register its resources.

A catalog contains one or many manifests and is used as a logical grouping of machines and/or platforms. The catalog is the layer where the conditions live, so the same manifest can be applied to a Windows machine and skipped on a Linux one.

The three levels also give a clean place for the logic. A resource is a single desired fact, a manifest is a recipe that composes resources, and a catalog says which recipes apply where. That is a small vocabulary, and a framework built on three nouns is easier to learn than one built on a configuration language with its own evaluation model.

A manifest reads like a script and describes a plan instead

The example manifest in the readme installs Chocolatey and then Visual Studio Code on a Windows machine, and it shows the shape of a resource well.

The chain starts with a download, which puts a file somewhere, and then a registry value that sets the PowerShell execution policy to Unrestricted at a path under HKLM. The install step is a PowerShell resource, and it carries the interesting modifiers: a flavor, RequireAdministrator, an Unless condition that skips the step if Chocolatey is already installed, and two After declarations that order it after the registry change and after the download.

The last resource is a Chocolatey package for vscode with an Ensure call for the desired package state, and it declares itself after the PowerShell step.

The ordering modifiers are what make this more than a list. Instead of a script that runs top to bottom and fails when something is missing, you describe steps and their dependencies, and the framework works out the sequence. The Unless condition is the same idea applied to a precondition rather than to an ordering.

And the whole thing is a declaration. The readme says it plainly: resources do not do anything when they are declared, they describe what will be done when executed. Nothing touches the machine until the run reaches the point where you approve it.

The catalog is where the platform condition lives

A catalog is a class that overrides Execute on a catalog context, and the example shows the condition that decides whether the manifest applies at all:

public sealed class MyWindowsComputer : Catalog
{
    public override void Execute(CatalogContext context)
    {
        if (!context.Facts.IsWindows())
        {
            return;
        }

        context.UseManifest<Chocolatey>();
    }
}

The context exposes facts about the machine, and the check is a single method call. What that structure buys is that the condition and the content live in the same place. The catalog says which manifests to use, and the facts decide whether this run applies to the machine it is running on.

The readme notes that the condition excludes non-Windows environments, which is honest about the current state of the example set: the resources shown are Windows specific, a registry key under HKLM and a Chocolatey package, so a catalog for a different platform would need different resources rather than only a different condition.

That is the shape a multi-platform deployment would take, one catalog per platform family, each pulling in the manifests that make sense for it, and it is a reasonable design because the facts are a first class concept rather than an environment variable you parse yourself.

The entry point is a host builder, and the run asks before it changes anything

To run the configuration you need an entry point, and the example is short:

public static class Program
{
    public static int Main(string[] args)
    {
        return CupboardHost.CreateBuilder()
            .AddCatalog<MyWindowsComputer>()
            .Run(args);
    }
}

The catalogs have to be added explicitly to the host builder, which is what makes the program self-describing: the set of things this program manages is right there in the source.

Then there is the run itself, and this is the part that distinguishes the tool. You run the program in a terminal with administrator rights, and it shows a summary of what will change, which you have to approve. The output has two panels. The first is a Plan table with a number, a Provider column and a Resource column, listing in this case the registry key, the download, the PowerShell script and the Chocolatey package. The second is a Breakdown with a bar per provider type and a count next to each one.

Then the confirmation:

WARNING: This will change the state of the current machine.
Are you sure you want to continue? [y/n] (n): _

The default answer is no. A provisioning tool that prints a plan and waits is a different contract from one that starts applying immediately, and for a tool that writes to HKLM and installs packages, that difference is the safety property that matters most. The diagnostic verbosity flag is what you want when you want to see more of what the framework is doing.

Cake builds it, and the readme says to use it at your own risk

The build uses Cake as a dotnet tool, so the repository expects you to restore it first:

> dotnet tool restore

and then the build is a single command:

> dotnet cake

The repository layout is small and matches that. There is a src directory with the code, a build.cs file which is where a Cake script lives, dotnet-tools.json which is the manifest that pins the tool, global.json which pins the .NET SDK version for the repository, plus an .editorconfig, a code of conduct, the licence and the readme.

The disclaimer deserves its own paragraph, because it is at the top of the readme rather than at the bottom. The project is currently in preview, and the instruction is to use it at own risk.

That word, preview, sits in tension with the rest of the design, which is careful. The plan, the approval prompt, the ordering modifiers, the Unless conditions, the facts abstraction, they are the details of a tool that has been thought about rather than sketched. But the author is explicit that it is not finished, and the release history supports that reading, since there are no GitHub releases at all, only commits.

For an adopter that combination is workable rather than alarming. The safest way in is the one the design already suggests: run it on a disposable virtual machine first, read the plan, and only then let it touch a machine you care about.

Editorial conclusion

Cupboard fits a .NET shop that wants machine configuration to live in version controlled C# rather than in a pile of PowerShell scripts, because the resource, manifest and catalog model gives the same code a place to describe files, registry values and packages, and the run prints a plan and waits for a yes. It is the wrong choice if you need something the project calls production, because the readme states that it is currently in preview and should be used at own risk, and it is the wrong choice if your estate is not Windows only, since the example catalog has to check the platform fact explicitly. Before you run it on anything you care about, read the plan output rather than the prompts, run the first pass on a throwaway virtual machine, and check the resources you depend on against the ones the framework actually implements.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. patriksvensson/cupboard on GitHub
4. README