Installing Stella Ops packages
Stella Ops publishes its .NET components as NuGet packages: the Router (a gateway and the microservices behind it), the Workflow engine, and the shared foundation libraries they use. This guide covers what every consumer does once: configure the feed, choose and pin versions, check package signatures, and install from the offline archive on a machine without a network.
For the packages of one component and the role of each, read the component’s package page: Router packages and Workflow packages.
Before you start
- .NET 10 SDK. The libraries target
net10.0. The Router source generator targetsnetstandard2.0and runs inside the compiler of any .NET 10 SDK. - The feed.
https://nuget.stella-ops.org/v3/index.json. Anyone can download from it without an account. - nuget.org. Stella Ops packages depend on third-party packages from nuget.org. The Stella Ops feed does not serve them, so a restore needs nuget.org or a mirror of it that your organisation approves.
If the feed lists no version of a package, that package has not been released yet.
Configure the feed
Put a nuget.config beside your solution. It takes every StellaOps.* package from the Stella Ops feed and every other package from nuget.org, with package source mapping:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="stellaops" value="https://nuget.stella-ops.org/v3/index.json" />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</packageSources>
<packageSourceMapping>
<packageSource key="stellaops">
<package pattern="StellaOps.*" />
</packageSource>
<packageSource key="nuget.org">
<package pattern="*" />
</packageSource>
</packageSourceMapping>
</configuration>
How it works:
- The longest matching pattern wins. Every
StellaOps.*id comes fromstellaops, every other id fromnuget.org. - A package with the same id on another feed cannot replace a Stella Ops package, because NuGet asks only the mapped source for that id.
<clear />keeps the sources of other configuration files (user-wide and machine-wide) out of this restore.
To use an internal mirror instead of nuget.org, change the value of the nuget.org source and keep the mapping.
Pitfall. Do not name the Stella Ops feed alone with --source. A restore that reads only that feed fails when a third-party dependency is not already in the local package cache.
Add a package
Every version is a prerelease in NuGet’s terms (see Versions), so name the version or pass --prerelease:
dotnet add package StellaOps.Microservice --prerelease
dotnet add package StellaOps.Workflow --prerelease
In Visual Studio, tick Include prerelease in the package manager. dotnet package search reports that the feed has no search service. Browse the packages, their versions and their release notes at https://nuget.stella-ops.org.
The Router gateway is also published as a .NET tool, StellaOps.Router.Gateway.Host. Router gateway host shows how to install and run it.
Versions
Every version has the form x.y.z-yyyyMMddTHHmmssZ, for example 1.2.3-20261102T141530Z: the release number, then the UTC time of the release. A plain x.y.z is never published. NuGet clients cache a version permanently, so a published version never changes.
NuGet reads the time suffix as a prerelease label. Choose the form that matches your goal:
| Goal | Use |
|---|---|
| The newest release, once | dotnet add package <id> --prerelease |
| One exact release, for reproducible builds | --version 1.2.3-20261102T141530Z, or Version="1.2.3-20261102T141530Z" in the PackageReference |
| The newest release of 1.2.3 at each restore | Version="1.2.3-*" in the PackageReference |
One version for a line
The Router packages form one line, and the Workflow packages form another. Every member of a line release has the same version and was built from the same commit. A member names that version of the other members as the minimum version of its dependency on them. Mixing versions of one line restores a combination that no release built and tested.
Keep a line on one version with central package management. In Directory.Packages.props at the root of the solution:
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<StellaOpsRouterVersion>1.2.3-20261102T141530Z</StellaOpsRouterVersion>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="StellaOps.Microservice" Version="$(StellaOpsRouterVersion)" />
<PackageVersion Include="StellaOps.Microservice.SourceGen" Version="$(StellaOpsRouterVersion)" />
<PackageVersion Include="StellaOps.Router.Transport.Tcp" Version="$(StellaOpsRouterVersion)" />
</ItemGroup>
</Project>
The project files then name the packages without a version (<PackageReference Include="StellaOps.Microservice" />). To upgrade the line, change one property. The version above shows the form only; use a version the feed lists.
The shared foundation libraries (for example StellaOps.Messaging) are released one library at a time, each with its own version. A line member names the foundation version it was built with, and NuGet restores it as a dependency, so you do not reference it yourself unless your code uses it.
Reproducible restores with a lock file
A float such as 1.2.3-* resolves to the newest release at each restore. For a build that restores the same packages every time, pin exact versions and use a lock file:
In each project, or once in
Directory.Build.props, set the property:<PropertyGroup> <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile> </PropertyGroup>Run
dotnet restoreand commit thepackages.lock.jsonfile it writes beside each project.In CI, restore with
dotnet restore --locked-mode. Expected result: the restore fails when the lock file no longer matches the project’s dependencies or a package’s content hash, instead of changing the build.
Checking a package’s signature
Every package on the feed is signed. NuGet does not check these signatures when it restores, so check them yourself when it matters: before a first use, in a release pipeline, or when you copy packages into an internal mirror.
The chain of keys
Four links, each checked with openssl:
- The release key,
https://stella-ops.org/keys/cosign.pub. Its SHA-256 is its key id, and the key id is fixed:91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. The same key signs Stella Ops images and release bundles. It never signs a package itself. - The keyring,
https://stella-ops.org/keys/nuget-signing-keys.txt. It verifies with the release key, usingnuget-signing-keys.txt.sigbeside it. - The package key. The keyring line whose validity window holds the timestamp in the package version, and which is not revoked. The key file it names, such as
nuget-signing.pub, sits beside the keyring, and its SHA-256 must equal the first field of the line. - The package. Its
.sigfile, served beside the package, verifies with the package key.
Each keyring line has five fields:
<sha256 of the key file> <status> <valid-from> <valid-until> <file>
The two times have the version form yyyyMMddTHHmmssZ. A key is valid for a package when valid-from is at or before the package’s timestamp and valid-until is after it. Windows may overlap while a new key takes over. The status is one of:
| Status | Meaning |
|---|---|
active | Signs new packages. |
retired | Signs nothing new. Packages it signed inside its window still verify. |
revoked | Nothing it signed verifies, whatever the date. |
A signature proves that the Stella Ops release host built and published the package from a commit on the main branch, after the release checks. It does not prove that a person reviewed the code.
Check one package
Download each file over HTTPS with any client and keep its file name. The commands need openssl, sha256sum and base64 in a POSIX shell (on Windows, Git Bash or WSL).
Download the release key and the keyring into an empty folder:
cosign.pub,nuget-signing-keys.txtandnuget-signing-keys.txt.sigfromhttps://stella-ops.org/keys/.Check the release key id:
sha256sum cosign.pubExpected result:
91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. Stop if it differs: a key with another id is not the Stella Ops release key.Check the keyring:
base64 -d nuget-signing-keys.txt.sig > keyring.sig.der openssl dgst -sha256 -verify cosign.pub -signature keyring.sig.der nuget-signing-keys.txtExpected result:
Verified OK.Read the timestamp from the package version (
20261102T141530Zin1.2.3-20261102T141530Z). Find the keyring line that is notrevokedand whose window holds that timestamp. Download the key file it names fromhttps://stella-ops.org/keys/, then compare its SHA-256 with the first field of the line:sha256sum nuget-signing.pubDownload the package and its signature. The feed serves them under lower-case names:
https://nuget.stella-ops.org/v3/flatcontainer/<id>/<version>/<id>.<version>.nupkgand the same address with.sigappended. ForStellaOps.Microservice1.2.3-20261102T141530Z,<id>isstellaops.microserviceand<version>is1.2.3-20261102t141530z.Check the package:
base64 -d stellaops.microservice.1.2.3-20261102t141530z.nupkg.sig > package.sig.der openssl dgst -sha256 -verify nuget-signing.pub -signature package.sig.der \ stellaops.microservice.1.2.3-20261102t141530z.nupkgExpected result:
Verified OK. Any other output means the package is not the one the release host published: do not use it.
To check a whole line release, repeat steps 5 and 6 for every member at the same version. Every member must verify, and every member must carry the same version.
The offline archive of a line release
A line release can also be published as one archive for machines without a network: stellaops-nuget-<line>-<version>.tar.gz, with its SHA-256 in stellaops-nuget-<line>-<version>.tar.gz.sha256 beside it. The download page of the component gives the archive’s address and digest for each release.
The archive has one top directory, stellaops-nuget-<line>-<version>/:
| Path | Content |
|---|---|
packages/ | A local NuGet feed: every member of the release, every Stella Ops package the members depend on at the exact version they name, and the .sig file of each package. No third-party package. |
keys/ | cosign.pub, nuget-signing-keys.txt and its .sig, and every package key the packages need. |
release-record.txt and release-record.txt.sha256 | The release record: the line, the version, the commit, the publication date and the SHA-512 of every member. |
component-release.props | The release properties for a rebuild of the release from its commit. |
SHA256SUMS | The SHA-256 of every other file, with paths relative to the top directory. |
The archive as a whole is not signed. Its integrity is the published SHA-256, and every package in it carries its own signature.
Check the archive
Compare the archive with its published digest. In the folder that holds both files:
sha256sum --check stellaops-nuget-router-1.2.3-20261102T141530Z.tar.gz.sha256Expected result:
stellaops-nuget-router-1.2.3-20261102T141530Z.tar.gz: OK.Extract it and check every file:
tar -xzf stellaops-nuget-router-1.2.3-20261102T141530Z.tar.gz cd stellaops-nuget-router-1.2.3-20261102T141530Z sha256sum --check SHA256SUMS sha256sum --check release-record.txt.sha256Expected result:
OKfor every file.Check the keys in
keys/and every package inpackages/as in Check one package, steps 2 to 4 and 6, with the files from the archive instead of downloads. The release key id must be the fixed id above: never accept an id the archive supplies.Check that
release-record.txtnames the line and version of the archive name, and that the SHA-512 of each member package equals itsmember:line:cat release-record.txt sha512sum packages/*.nupkg
Use the archive as a local feed
Map StellaOps.* to the extracted packages/ folder and keep a source for every other id:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="stellaops-offline" value="stellaops-nuget-router-1.2.3-20261102T141530Z/packages" />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</packageSources>
<packageSourceMapping>
<packageSource key="stellaops-offline">
<package pattern="StellaOps.*" />
</packageSource>
<packageSource key="nuget.org">
<package pattern="*" />
</packageSource>
</packageSourceMapping>
</configuration>
A relative path is read from the folder of the nuget.config. On a machine without a network, replace the nuget.org source with a local folder or an internal mirror that holds the third-party packages, or restore them into the package cache first.
What a line release gives you
One version, one commit. Every member has the same version, built from the same commit.
A publication date in every assembly. Every member assembly carries the assembly metadata
StellaOps.Component.PublishedAtwith the UTC date of the version timestamp:2026-11-04for1.4.0-20261104T101500Z. A component licence file uses this date. An assembly without the metadata comes from a development build, not from a release.A release record. The offline archive carries it as
release-record.txt:Release record: stellaops.nuget-line-release/v1 line: <line> version: <version> commit: <40-character commit id> published-at: <UTC date of the version timestamp> member: <member> <version> <package SHA-512>There is one
memberline per member.
Rules for consumers
| Rule | Why |
|---|---|
Take StellaOps.* packages only from the Stella Ops feed or its offline archive, with package source mapping | NuGet otherwise takes a package from whichever source answers first |
| Give every package of one line the same version | A member names that release’s version of the other members as its minimum; mixing releases restores a combination no release built |
| Pin exact versions and restore with a lock file for reproducible builds | A float such as 1.2.3-* resolves to the newest release at each restore |
| Expect a published version never to change | A withdrawn version is only hidden from listings; an exact reference to it still restores |
| Check signatures before a package enters your build or mirror | NuGet does not check these signatures on restore |
| Expect build-time analyzers with some packages | A package with analyzer assets runs them in every project that references it: StellaOps.Microservice.SourceGen generates the Router endpoint registration, and the Workflow abstractions package brings the workflow definition analyzer |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Unable to find package StellaOps.<name> | The nuget.config does not map StellaOps.* to the feed, or no version has been released | Check the mapping; browse https://nuget.stella-ops.org for the package |
| A third-party package is not found | The restore reads only the Stella Ops feed | Keep nuget.org or your mirror in packageSources and in the mapping |
NU1603 or a version you did not ask for | A float or a minimum version resolved to another release | Pin the exact version of every member of the line |
NU1004 in CI | The lock file differs from the resolved graph | Restore locally, review the lock file change, commit it |
| The package manager shows no versions | Prerelease versions are hidden | Pass --prerelease, or tick Include prerelease |
