Piranha CMS: an editor-first .NET CMS that runs integrated or headless

One library, three ways of serving the same content

Piranha describes itself twice, and the two descriptions are worth reading together. The repository description calls it an editor-focused CMS for .NET that can be used both as an integrated CMS or as a headless API. The README calls it a decoupled, cross-platform CMS built for .NET 8 and Entity Framework Core. Both are accurate and they describe a design where the content model, the storage layer and the delivery surface are separable rather than welded together.

The topic list spells out the delivery targets: asp-net-core, asp-net-core-mvc, asp-net-core-razor-pages, cms, cms-framework, dotnet-core, entityframeworkcore and piranha. Two of those are the fork in the road. Razor Pages and MVC hosts render pages server-side, which is the integrated mode, and the headless mode exposes the same content over an API for a separate frontend to consume.

For an evaluator, that means the interesting question is not whether Piranha can do headless, because almost every CMS claims that now, but where the line sits. In the repository layout the answer is partly visible: `core/` holds the CMS itself, `identity/` is a separate top-level project for authentication, `data/` sits apart again, and `examples/` contains exactly two hosts, `examples/MvcWeb` and `examples/RazorWeb`. Two example hosts, no separate API example, suggests the integrated path is the one the project actively demonstrates, and headless is a mode you configure rather than a reference application you copy.

Templates have to be installed before dotnet new knows about them

The getting started path does not begin with a clone. It begins with a NuGet package that registers templates into the dotnet CLI:

dotnet new install Piranha.Templates

Only after that does the project template command exist:

dotnet new piranha.razor

That ordering matters because template discovery in the dotnet CLI is global rather than per-project. Installing a package adds the templates to your user profile, which is why the README tells you to create an empty folder first and notes that the default behaviour names the new project after its containing folder.

The README also warns about a specific trap worth internalizing: naming your project `Piranha` will produce a circular reference error at restore time. The README attributes this to a limitation in `dotnet restore`, and the practical advice is to avoid the exact name of the framework package rather than trying to work around it. This is the sort of detail that normally lives in a wiki article, and its presence in the README is a mild signal about how the project documents itself.

The prerequisites are short: the .NET 8.0 SDK and an editor. Templates are documented further at piranhacms.org under project templates, so the README deliberately hands off the full catalogue rather than enumerating it.

Building from source ends in one of two example hosts

The source route is a standard SDK workflow, and the useful part is the last two lines:

> git clone https://github.com/PiranhaCMS/piranha.core.git
> cd piranha.core
> dotnet restore
> dotnet build
> cd examples/MvcWeb
> dotnet run

`Piranha.sln` at the root, plus `Directory.Build.props` and `Directory.Build.targets`, means version and packaging settings are centralised rather than repeated per project. The root also carries `pack.sh`, `test.sh`, `build/` and `sign.json`, which is the conventional shape for a repository that ships signed NuGet packages rather than just source. The NuGet badge in the README points at a package called `Piranha` while the repository is `piranha.core`, so the package you consume and the repository you read are not named the same thing.

Swapping `examples/MvcWeb` for `examples/RazorWeb` is the entire difference between the two demonstrated hosts. That is a small enough surface that you can read both, and it is a good reason to start from source even if you ultimately install the template.

The Manager's frontend assets are built separately, which is worth knowing before you expect a clean clone to produce a working admin screen:

> cd piranha.core/core/Piranha.Manager
> npm install
> gulp min:js
> gulp min:css

So a first run from source has three toolchains in play: the .NET SDK, npm, and gulp. The template path avoids all of that, which is the practical argument for using it.

The Manager ships with admin/password and tells you to remove it

The Manager lives at `~/manager`, and the README publishes the default credentials openly: `admin` / `password`. It follows that with production advice, which is unusually direct for a README: remove the user, or change the password, and update the password strength policy. It links to the authentication documentation on piranhacms.org for the mechanics.

The separate `identity/` directory in the repository tree is consistent with that. Authentication is a distinct concern from the CMS core, which is what makes it possible to describe the project as both decoupled and opinionated about login. The `core/Piranha.Manager` path used in the asset build commands is a second, separate location, so the manager has both a project identity under `identity/` and a UI project under `core/`.

The July 2026 security release adds a detail that changes how you should read the default credentials. Version 12.2 fixed an issue where non-matching passwords were exposed in an error message. That is a small class of vulnerability, and it is the kind that exists precisely because a password check was surfaced too verbosely somewhere in the authentication path. Combined with the stored XSS fixes in the same release, it is a reminder that the manager is a normal web application with normal web application weaknesses, and that shipping the default user unchanged is not a defensible production posture.

Two security releases one day apart, after a sixteen month gap

The release history is short and revealing. Version 12.0 shipped on 2025-03-22 and was a broad maintenance release: updated XSitemap, fixed alias routing case sensitivity, completed Open Graph tags, added async support to the ICache interface, updated Markdig, sanitized HTML output from the Markdown field, disabled preview for PDF documents, cross-compiled for .NET 8 and .NET 9, and moved to ImageSharp 2.1.10. The contributor thanks at the top of that release name two people.

Then a sixteen month gap, and two releases a day apart in July 2026. Version 12.1 on 2026-07-15 addressed an ImageSharp vulnerability and a stored XSS issue tracked as CVE-2025-57692. Version 12.2 on 2026-07-16 called itself a minor security update resolving all reported CVE reports, and listed five items: XSS in meta fields for pages and posts, non-matching passwords exposed in an error message, and CVEs 2025-61413, 2025-67291 and 2025-67290.

Two facts sit side by side and the README does not reconcile them. The prerequisites say .NET 8.0 SDK, and the repository topics still include `dotnet6`, while release 12.0 explicitly cross-compiles for both .NET 8 and .NET 9. So the target framework list is wider than the documented prerequisite and wider than the topic tag suggests. If you are pinning a runtime, check the package's target frameworks in NuGet rather than trusting either the README or the topic list.

The last push to the repository was on 2026-08-09, after both security releases, so the working state is newer than v12.2 rather than older.

Funding, localisation and a 100 item issue tracker

The repository carries Open Collective sponsor and backer badges alongside Gitter chat links, and the README points at an Open Collective page for monthly support. Two commercial sponsors are listed. There is also a `SECURITY.md` at the root and a `CONTRIBUTING.md`, which together with `crowdin.yml` and a Crowdin badge suggest a project with a defined process for contributions, translations and vulnerability reports rather than an informal one.

Translation is worth pausing on for an editor-focused CMS. Crowdin means the manager interface can be localised by contributors rather than by the maintainers alone, and `crowdin.yml` at the root is where the resource wiring lives. For a CMS aimed at non-technical editors, interface translation is not a nicety.

The scale figures tell a similar story. 2,196 stars and 611 forks is a solidly adopted project, and the fork ratio is high enough to suggest people are deploying it rather than only reading it. Against that, 100 open issues is a real backlog, and the recent release bodies are dominated by security fixes and dependency updates rather than feature work. That combination, an established user base with a maintenance-shaped release cadence and a substantial issue count, is what you would expect from a CMS that has reached the stage where the work is keeping a large installed base safe rather than winning new users.

For a reader deciding whether to adopt, the concrete starting point is the piranha.razor template. Read `examples/MvcWeb` and `examples/RazorWeb` to see which host shape fits your team, check the current NuGet target frameworks before pinning, and replace the default admin user before the site is reachable by anyone else.

Editorial conclusion

Piranha is a good fit when the people publishing content are not developers and you want a .NET stack rather than a bolted-on admin panel. The Manager at ~/manager, the templates and the EF Core persistence give you the conventional CMS shape, and the headless option means the same content can feed a frontend you control. The security track record is the part to weigh: two releases a day apart in July 2026 fixing stored XSS, exposed password comparison errors and named CVEs means you should treat upgrades as routine rather than optional. Start from the piranha.razor template, delete the default admin user immediately, and pin your package version deliberately.

Frequently asked questions

Official sources

1. License: MIT
2. PiranhaCMS/piranha.core on GitHub
3. Project website
4. README
5. Releases