π«π· Version franΓ§aise
NuGet publication matrix
This file is the single source of truth for which projects are published to NuGet, so the
workflows (ci.yml validation, publish.yml pack + push on tag and the dev channel on green
main, release.yml installers)
never drift.
Status. Distribution is one
Orkeonpackage plus thirteen opt-ins β fourteen packages, the listpublish.ymlpushes β guarded by thescripts/check-package-closure.pygate and pushed to NuGet.org through Trusted Publishing. The scripting naming is settled by ADR-007: the command library isOrkeon.Cli.Commands.Scripting, theorkeontoolOrkeon.Scripting.Cli.
The NuGet.org lineup
One package installs the whole framework; everything else in the lineup is an opt-in kept separate only because of what it would force on every consumer (dependency weight, native runtimes, a pre-release upstream).
| PackageId | Why |
|---|---|
Orkeon |
The umbrella package β the thirteen assemblies of the core closure (Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure, Orkeon.Constants.{Llm,FileSystem,Configuration,Protocol}, Orkeon.Tools.Abstractions, Orkeon.Analysis.Abstractions, Orkeon.Rag.Abstractions, Orkeon.Analysis, Orkeon.Rag, Orkeon.Plugins) embedded in one nupkg. One install = the complete framework: agents, crews, six orchestration modes, 16 LLM providers, 6 memory stores, RAG, RaggableTree. The Clean Architecture split stays a source-layout discipline, not a distribution contract. |
Orkeon.Tools |
The nine built-in tool families (Analysis, Code, Data, Drive, Email, EventHub, FileSystem, Rag, Web) in one nupkg. Separate from Orkeon only for dependency weight: the Data tools pull database drivers, PDF and spreadsheet libraries, the e-mail tools MailKit and MimeKit β dependencies a consumer who never uses them should not inherit. Depends on Orkeon. |
Orkeon.Rag.Onnx, Orkeon.Rag.Onnx.Model |
Opt-in ONNX cross-encoder reranker pair (runtime + embedded int8 weights) β pushed together; native onnxruntime payload. Orkeon.Rag.Onnx depends on Orkeon; Orkeon.Rag.Onnx.Model is dependency-free (embedded resources only) and is referenced alongside it. |
Orkeon.Tools.Embeddings.Local |
Local on-device embeddings (BGE-micro-v2 ONNX). Stays outside the umbrella because it carries a pre-release SmartComponents dependency from an archived upstream β putting it in Orkeon would force that pre-release on every consumer. Depends on Orkeon. |
Orkeon.Constants.Cli |
The shared CLI vocabulary: the option names the runners accept (RunOptionNames), their exit codes (RunExitCodes) and the session-state keys (SessionStateKeys), for a tool that drives orkeon run. A zero-dependency satellite (ADR-009), packed straight from its project; Orkeon.Scripting depends on it rather than embedding it. |
Orkeon.Scripting |
Runs a crew.ork.ts inside a .NET application, without starting a process: services.AddOrkeonScripting() then ICrewScriptRunner.RunAsync(path), relative paths resolved against the process working directory β see Orkeon.Hosting. Embeds Orkeon.Scripting (the Jint host, the esbuild bundler driver, the DSL typings as an embedded resource), Orkeon.Hosting (the runner bootstrap orkeon run and orkeon-host share). Separate from Orkeon because the runner host composes every built-in tool family: it depends on Orkeon, Orkeon.Tools, Orkeon.Tools.Embeddings.Local and Orkeon.Constants.Cli (so on their database drivers, MailKit and the SmartComponents pre-release), plus Jint, Microsoft.Extensions.Hosting and CommandLineParser. esbuild is not shipped, as for the tool. |
Orkeon.Scripting.Cli |
The orkeon dotnet tool (PackAsTool; the PackageId is the install command β ADR-007). Publishable on NuGet.org: the iOS/Android onnxruntime natives a CLI tool can never load are excluded, in every tool package: about 187 MB with the natives of every desktop runtime (win, linux, osx), under the 250 MB nuget.org limit. |
Orkeon.Compliance.Vfs |
The Roslyn analyzer that refuses direct System.IO in your own code (rules ORKVFS001βORKVFS007, analyzers/dotnet/cs, DevelopmentDependency). Standalone by design: it depends on nothing from Orkeon and works in any C# project β add the PackageReference, build, and every File.*/Directory.* call is a diagnostic. |
Orkeon.Interop.AgentFramework |
The bridge to Microsoft Agent Framework, both ways: an Orkeon crew as a MAF AIAgent (CrewAgent), a MAF AIAgent as the brain (WithAgentFrameworkAgent) or as a tool (WithAgentFrameworkTool) of an Orkeon agent. Separate from Orkeon because the Microsoft.Agents.AI.Abstractions dependency is a consumer's choice. Depends on Orkeon. |
Orkeon.Hosting.Aspire |
The .NET Aspire hosting integration: AddOrkeonHost (the orkeon-host daemon) and AddOrkeonCrewRun (one orkeon run) as AppHost resources, WithOrkeonModel / WithOrkeonSetting for the ORKEON_ environment, OTLP export wired so the dashboard reads the run. Separate from Orkeon because Aspire.Hosting is an AppHost's choice. Depends on Orkeon. |
Orkeon.Cli.Abstractions |
The contracts of the interactive runners and command registries (IConsoleAdapter, the command registry, the runner options). No Orkeon dependency: two Microsoft.Extensions abstractions only, packed straight from its project. |
Orkeon.Cli.TerminalGui |
The Terminal.Gui v2 split-pane console (REPL + logs pane) that terminal applications build on. Separate from Orkeon for its Terminal.Gui dependency. Depends on Orkeon (which carries the Orkeon.Constants.Configuration it reads) and Orkeon.Cli.Abstractions. |
Orkeon.Templates |
The dotnet new templates: orkeon-host (a generic host that runs a crew in its own process, shaped like the orkeon-host daemon), orkeon-plugin (an IOrkeonPlugin, one tool and its plugin.json) and orkeon-tool (a ToolBase class). PackageType=Template: no assembly, no dependency. A generated project references Orkeon (and Orkeon.Scripting for the host) at the version of the template package, written out in its project file. |
How the packaging projects are built
- The lineup nupkgs come from dedicated packaging projects under
src/packaging/β nine of them: theOrkeonandOrkeon.Toolsumbrellas, theOrkeon.Templatescontent package, plus theOrkeon.Rag.Onnx.Package,Orkeon.Tools.Embeddings.Local.Package,Orkeon.Interop.AgentFramework.Package,Orkeon.Hosting.Aspire.Package,Orkeon.Scripting.PackageandOrkeon.Cli.TerminalGui.Packagewrappers, which pack the opt-in assemblies with a nuspec dependency on theOrkeonumbrella β and, forOrkeon.Scripting, onOrkeon.Tools,Orkeon.Tools.Embeddings.LocalandOrkeon.Constants.Clitoo, forOrkeon.Cli.TerminalGuionOrkeon.Cli.Abstractions. A dependency on a wrapper is spelled by referencing the project it wraps, whose restore name is the public id (the wrapper's own is<id>.Package); the closure gate accepts exactly that reference. The remaining lineup packages are packed straight from their own project:Orkeon.Rag.Onnx.Model(src/rag/), theorkeontool (src/scripting/Orkeon.Scripting.Cli), the analyzer (src/analyzers/Orkeon.Compliance.Vfs),Orkeon.Constants.CliandOrkeon.Cli.Abstractions, which depend on no other Orkeon assembly. The embedded library projects themselves areIsPackable=falseand their source layout, namespaces and per-assembly PublicAPI freeze are untouched; the real opt-in projects keep normalProjectReferences, so in-repo consumers are unaffected β only the wrappers carry the embed pattern below. - Each packaging project references its embedded project(s) with
PrivateAssets="all"(keeping them out of the nuspec dependency list) and packs their DLL+XML intolib/. BecausePrivateAssets="all"also stops the embedded projects' externalPackageReferences from flowing into the nuspec, the union of those references is re-declared by hand in the packaging csproj. scripts/check-package-closure.py(run bypublish.ymlright after the pack, on the tag and on the dev channel) fails the workflow if (1) a lineup package declares anOrkeon.*dependency outside the lineup β the NU1101 class of incident β (2) an umbrella's hand-declared externals drift from what its embedded projects actually require, or (3) an assembly an embedded one reaches transitively ships nowhere in the lineup. Its source half (no nupkg needed) also runs on every pull request throughscripts/check-doc-claims.py, which additionally fails when a packable project is neither in the lineup nor GitHub-Packages-only, or when one of the hand-written copies of the lineup drifts.publish.ymlpushesOrkeonfirst: the other lineup packages depend on it and NuGet does not order pushes, so pushing a dependent first would expose a package whose restore fails.
Discontinued packages
The following projects are not packed under their own id (IsPackable=false): Orkeon.Domain,
Orkeon.Application, Orkeon.Infrastructure, the Orkeon.Constants.{Llm,FileSystem,Configuration,Protocol} satellites,
Orkeon.Analysis, Orkeon.Analysis.Abstractions, Orkeon.Rag, Orkeon.Rag.Abstractions,
Orkeon.Tools.Abstractions and the nine Orkeon.Tools.<family> projects, Orkeon.Cli,
Orkeon.Cli.Commands.Scripting, Orkeon.Hosting, Orkeon.Plugins. Those that the Orkeon and
Orkeon.Tools umbrellas embed still ship β inside the umbrella's nupkg, not under their own id (Orkeon.Plugins is the thirteenth assembly of Orkeon);
Orkeon.Hosting ships inside the Orkeon.Scripting package, the opt-in that carries the scripting layer.
Migration: the source code and namespaces are unchanged, so consumer code compiles as-is β
only the install changes. Uninstall the per-layer packages and
dotnet add package Orkeon (add Orkeon.Tools if you used a
Orkeon.Tools.<family> package other than Embeddings.Local).
NuGet.org state
The Orkeon prefix (the bare id and Orkeon.*) is reserved on nuget.org for the owner account
arion-orkeon. The per-layer packages Orkeon.Domain, Orkeon.Application and
Orkeon.Infrastructure are unlisted, not deleted: a consumer pinning one still restores. A freshly
pushed package is not downloadable until NuGet.org has validated it; --skip-duplicate makes a
re-push a no-op.
Published to GitHub Packages
publish.yml (tag v*) packs Orkeon.sln and pushes every packable project to
GitHub Packages (nuget.pkg.github.com/Orkeon) with --skip-duplicate. That is the
NuGet.org lineup above plus the build-time and runner packages that stay off NuGet.org:
Orkeon.ConsoleApp and Orkeon.Generators:
| PackageId | Tool command | Source project |
|---|---|---|
Orkeon.ConsoleApp |
orkeon-repl |
src/apps/Orkeon.ConsoleApp |
The other dotnet tool, Orkeon.Scripting.Cli (command orkeon), is in the NuGet.org lineup above.
Dev channel: the latest main, between two tags
Once ci.yml is green on a push to main, the publish-dev job of publish.yml packs the
same projects as <X.Y.Z>-<pre>.dev.<n>, n being the number of that CI run β so
<X.Y.Z>-<pre>.dev.412 is the commit CI run #412 validated β and pushes them to GitHub
Packages only: never NuGet.org, which can unlist a version but never delete it.
scripts/prune-dev-packages.sh then deletes the older dev builds, so the feed holds every
tagged release plus the latest green main, nothing in between. A tagged version is never
deleted; a version that is neither tagged nor a dev build is reported, not deleted β the
same script removes those in a one-off, reviewed run (--include-untagged, dry run first).
SemVer puts
<X.Y.Z>-<pre>.dev.<n>above<version>and below the next pre-release, so--prereleaseresolves the dev build. When the props version has no suffix (a stable release), the dev builds move to the next patch β1.0.1-dev.<n>after1.0.0β because1.0.0-dev.<n>would sort below the release.A dev version lives until the next green merge. A
PackageReferencepinned to one keeps restoring β NuGet reads the version as a minimum and takes the next build up, with warning NU1603 (an error under warnings-as-errors) β but exact pins break: adotnet toolmanifest, apackages.lock.jsonin locked mode. Float (*-*, anddotnet restore --force-evaluateto move to the newest) to follow the channel; pin a tagged version for anything durable.A dev build is not a release: no attestation, no SBOM, nothing on NuGet.org.
Two forms off a tag, one calculation.
scripts/resolve-version.sh(and its PowerShell twinscripts/resolve-version.ps1) names every build that is not a release:Form Comes from Example <X.Y.Z>-<pre>.dev.<n>CI alone β publish.ymlandapt-dev.yml,nbeing the CI run number<X.Y.Z>-<pre>.dev.412<props version>.local.<stamp>a build made from a checkout β scripts/package-installers.shor.ps1without a version, a manual run ofrelease.yml<version>.local.202610080430<stamp>is the committer date of the commit built,YYYYMMDDHHMMin UTC: it orders two local builds, and a shallow clone gives the same one. Uncommitted changes do not move it. SemVer sorts a local build above every dev build of the same props version and below the next one, so a machine installed from the sources is never taken for an older build. On the commit av*tag points to, the same scripts answer the tag's version.dotnet buildis not concerned: the assemblies of a plain build carry the props version.Once the feed is a source,
--prereleaseand floating versions resolve dev builds for every Orkeon package, the NuGet.org ones included;--versionpins a release.GitHub Packages requires a token even for a public repository: a personal access token (classic) with
read:packages. Run the commands outside a clone of this repository β inside one, itsnuget.configkeeps nuget.org as the only source and you would get the latest tag instead.
Step by step β the token, both shells, checking what runs, going back to the releases:
Follow main: the dev channel.
dotnet nuget add source https://nuget.pkg.github.com/Orkeon/index.json \
--name orkeon-github \
--username <your-github-username> \
--password <PAT-with-read:packages> --store-password-in-clear-text
dotnet tool install -g Orkeon.Scripting.Cli # installed already: dotnet tool update, same arguments
# in a project: <PackageReference Include="Orkeon" Version="*-*" />
Installer archives (release.yml)
On a v* tag, release.yml builds every installer artifact, smokes each onboarding
channel on a real runner (Windows CLI zip, Windows service, Debian package, macOS
tarball), and only then attaches everything to the GitHub Release. The pipeline is
installers β {smoke-windows, smoke-windows-service, smoke-deb, smoke-macos, msi} β release β {verify-published, apt-publish β verify-apt} (the last two are described in
The apt repository); behind those same five jobs, docker-image pushes the ghcr.io/orkeon/orkeon
container image to GHCR (one multi-platform tag, linux/amd64 and linux/arm64, checked
once pushed) in parallel with release, so a red smoke moves neither the
Release nor the :latest tag. workflow_dispatch runs
the same thing minus the publication (no tag, no Release to attach to). A tag carrying a
pre-release segment (v<version>-<pre>) is published as a prerelease, so it never becomes the
repository's latest release; a bare v<version> does. The orkeon CLI runs the examples
(orkeon run crew.yaml runs the examples/ YAML crews; orkeon run script.ork.ts runs the
scripting DSL).
| Artifact | Built by | Contents | Runtime |
|---|---|---|---|
orkeon-<version>-<rid>.tar.gz / .zip |
package-installers.sh (default --app-set full) |
every launcher β orkeon, orkeon-slim, orkeon-repl, orkeon-host β + one shared esbuild + the deploy/ tree (systemd unit, SCM registration script, Dockerfile.host) |
mixed: orkeon-slim is framework-dependent, every other launcher (orkeon, orkeon-repl, orkeon-host) is self-contained |
orkeon-cli-<version>-win-x64.zip |
package-installers.sh --app-set cli --rids win-x64 |
the orkeon CLI + install.cmd and install.ps1 |
self-contained |
orkeon_<version>_amd64.deb / orkeon_<version>_arm64.deb |
package-deb.sh --arch amd64\|arm64 (reuses the linux-x64 and linux-arm64 staging trees β one publish, two packages per architecture) |
the orkeon CLI at /usr/bin/orkeon + the REPL at /usr/bin/orkeon-repl (it uses the one esbuild under /usr/lib/orkeon) |
self-contained; Depends on system libraries only (libicu78 down to libicu70, libssl3t64 \| libssl3, libc6 (>= 2.34)β¦, so Debian 12/13 and Ubuntu 22.04 to 26.04), never on dotnet-runtime-*; Recommends: orkeon-archive-keyring; ships md5sums (dpkg -V orkeon); byte-identical across two builds of the same commit (SOURCE_DATE_EPOCH) |
orkeon-archive-keyring_<YYYY.MM.DD>_all.deb |
package-keyring-deb.sh, once per keyring version (a date, such as 2026.10.04, from installers/apt/keyring.version); later Releases attach the bytes already published, never a rebuild |
/usr/share/keyrings/orkeon-archive-keyring.gpg, the public key of the apt repository |
β |
orkeon-<version>-win-x64.msi |
build-msi.ps1 (WiX, per-user scope), harvesting the extracted CLI zip |
the orkeon CLI, same pruned publish as the zip |
self-contained |
orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz |
package-installers.sh --app-set cli --rids osx-arm64 osx-x64 (cross-published from the ubuntu runner) |
the orkeon CLI alone + install.sh (the macOS channel stays CLI-only) |
self-contained |
orkeon-typings-<version>.tar.gz |
the installers job, step Package the editor typings: orkeon typings run on the orkeon of the linux-x64 staging tree, packed reproducibly (sorted names, the commit date as mtime, no gzip header) |
a folder of the same name holding orkeon.d.ts (the .ork.ts DSL) and orkeon-cli.d.ts (the *.cmd.ts commands), so a script project can pin and diff the typings of a release (Editor setup) |
β |
SHA256SUMS |
the installers job's packaging scripts (package-deb.sh refreshes its own line) |
one line per artifact above except the MSI, plus the SBOM (orkeon-<version>.sbom.cdx.json) and the typings archive |
β |
orkeon-host-<version>-win-x64.msi |
build-msi-service.ps1 (WiX, per-machine scope), harvesting the extracted full zip |
the self-contained orkeon-host publish alone, registered as the Orkeon service under NT SERVICE\Orkeon (no CLI, no wrapper, no deploy/ β the package registers declaratively) |
self-contained |
SHA256SUMS.msi |
build-msi.ps1 then build-msi-service.ps1, in order, in the msi job |
the two MSIs | β |
The service host
orkeon-host ships inside the full archive (--app-set full), self-contained: a daemon supervised by systemd or the Windows SCM must not depend on a runtime someone may upgrade underneath it. It is not a dotnet tool β it is installed as a service, not invoked from a shell. On Windows it also ships as its own per-machine MSI (orkeon-host-<version>-win-x64.msi), a separate product from the per-user CLI MSI: the two coexist, and the package registers the service declaratively β same account, same paths, same recovery as the script channel.
Its deployment artifacts live in deploy/ and ship inside the full archive next to the daemon: a systemd unit (Type=notify, restart on failure β config errors exit 78 and do not loop, hardened), a PowerShell script registering it with the SCM, and a Dockerfile. None of the three carries a secret β the bot token and the API keys are named by environment variable in the configuration and provided by the machine, so a unit file or an image layer can be read by anyone without leaking anything.
What the machine needs. No artifact of this table needs .NET where its Runtime column says self-contained; what the Windows ones need from Windows is not in that column:
| Artifact | On the machine |
|---|---|
orkeon-cli-<version>-win-x64.zip, orkeon-<version>-win-x64.zip |
nothing to install, no setting to change: install.cmd starts install.ps1 on Windows PowerShell 5.1, the one Windows ships, under an execution policy that holds for that one command. install.ps1 is written for 5.1 and for PowerShell 7, and smoke-windows installs the CLI zip under both. Windows may ask to confirm a file a browser downloaded (Unblock-File on the zip avoids it); a policy set by Group Policy overrules the launcher β only a signed script runs there |
orkeon-<version>-win-x64.msi |
nothing to install. Not code-signed: SmartScreen names an unknown publisher and asks before running it |
orkeon-host-<version>-win-x64.msi |
administrator rights (per-machine). Not code-signed either: same SmartScreen screen, and an elevation prompt without a publisher |
The steps a reader follows are in Before you start.
Two checksum files rather than one: the ubuntu installers job writes SHA256SUMS before
the MSI exists β it is built later, on windows-latest. Each checksum file is generated by
the job that produced the artifact it covers.
Blocking smokes. smoke-windows (a windows-latest runner) installs
orkeon-cli-*-win-x64.zip and walks the onboarding chain on it; smoke-deb (a stock
ubuntu-latest image for amd64, an ubuntu-24.04-arm runner for arm64 β each entry refuses a
runner of the other architecture) installs the .deb through apt, checks dpkg -V orkeon
is silent, walks the same chain, then removes the package β the linux-x64 tarball smoke runs
on the amd64 entry; smoke-macos (a macos-latest, Apple-silicon runner) extracts the osx-arm64
tarball, installs it with install.sh and walks the same chain before uninstalling; the msi
job runs its own msiexec /i /qn β orkeon doctor --json β msiexec /x /qn chain, asserting
the install directory, the ARP entry and the user PATH entry appear and then disappear.
smoke-windows-service installs the full win-x64 zip's service channel β virtual account,
--working-dir proven with a relative crew path, a refused configuration that stops without
looping and lands in the event log β and the msi job smokes the service MSI the same way,
plus a silent reinstall of itself. Every one of them also checks the notices of what it
installed: the license, THIRD-PARTY-NOTICES.md and one licenses/<pack>/ per .NET runtime an
application bundles, the runtimes being read from the payload itself (each
*.runtimeconfig.json), not from a list. And each asserts the channel its install names β
zip, msi, msi-host, deb or tarball: the INSTALL-CHANNEL file every packaging writes
at the root of what it installs, read back through orkeon --version --verbose (from the file
itself for the service MSI, which carries no CLI). All of them install from the job artifacts, never
from the Release, so a broken payload is caught before anything is published β the release
job needs them all.
After publication. release.yml calls release-verify.yml in its verify-published job,
right after the release job of the same run (and it can be run on demand for a given tag). A
release: published trigger would never fire: a Release created with the workflow's
GITHUB_TOKEN starts no other workflow. It downloads the assets from the Release page,
checks that every published asset has exactly one line in SHA256SUMS or SHA256SUMS.msi
and every line names a published asset, verifies every checksum with no line skipped, and
replays the onboarding smokes of both .deb (amd64, and arm64 on an ARM runner) and of the
osx-arm64 tarball on them β catching an asset that an upload, a replace or a tamper made
different from what the smokes above installed. The two smoke jobs check the tag out, so the
smokes replayed are the tag's own: an older Release is asked what its own smokes asked of it,
not what main's ask today. Run by hand on the two earliest Releases with installers, it
fails by design: they predate the naming rule below, and carry no arm64 package.
smoke-macos is also the only place the Gatekeeper and code-signing story is exercised: an
unsigned, quarantined or malformed native library (libtree-sitter*.dylib, onnxruntime, the
esbuild binary) is killed at load time, so it fails there rather than in a user's terminal.
The .deb file name carries the tag's version (orkeon_<version>_amd64.deb), while the
package's Version: field replaces - with ~ (<X.Y.Z>-<pre> becomes <X.Y.Z>~<pre>) so a pre-release sorts before
its final under dpkg. The two differ on purpose: GitHub rewrites ~ in an uploaded asset
name, and apt reads the file name from its index, never from the package. No asset name
carries a character outside [A-Za-z0-9._-] β scripts/check-release-assets.sh fails the
installers job, and the release job before publishing, otherwise β so SHA256SUMS lists every asset under the name it is published with. (The two earliest
Releases with installers predate the rule: their .deb was published with . in place of ~
while their SHA256SUMS names it with ~.)
The MSI's ProductVersion drops the suffix instead: Windows Installer versions carry only three
numeric fields, so build-msi.ps1 truncates <X.Y.Z>-<pre> to <X.Y.Z> for the property that
<MajorUpgrade> actually compares. Nothing is silently lost β the full string survives in the
.msi filename (orkeon-<version>-win-x64.msi) and in the ARPCOMMENTS property shown in
"Installed apps".
The orkeon CLI is distributed through eight channels:
| Channel | Artifact | Runtime | Audience |
|---|---|---|---|
| NuGet dotnet tool | Orkeon.Scripting.Cli (PackAsTool, command orkeon) |
needs .NET 10 SDK (dotnet tool install) |
.NET developers. Part of the NuGet.org lineup; the iOS/Android onnxruntime natives are excluded, which keeps it about 187 MB with every desktop runtime, under the 250 MB limit |
Windows zip + install.cmd |
orkeon-cli-<version>-win-x64.zip |
self-contained | Windows onboarding β the recommended channel |
| Windows MSI (per-user) | orkeon-<version>-win-x64.msi |
self-contained | Windows, double-click install and an "Installed apps" entry. One channel at a time: the MSI refuses to install over a zip install |
| Debian / Ubuntu apt repository | the .deb packages below, indexed on the apt branch (channels stable, rc, dev) |
self-contained | Debian / Ubuntu, amd64 and arm64 β the recommended channel: apt install, apt upgrade. See The apt repository |
| Debian package | orkeon_<version>_amd64.deb / _arm64.deb |
self-contained | Debian / Ubuntu without the repository (one version, no updates). Ships the orkeon-repl REPL next to the CLI |
macOS tarball + install.sh |
orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz |
self-contained | macOS onboarding today; install.sh clears the Gatekeeper quarantine attribute and ad-hoc re-signs the Mach-O files codesign -v rejects |
| Homebrew | the same osx tarballs, via installers/homebrew/orkeon.rb |
self-contained | macOS, once the tap exists β not published yet, see below |
| Multi-app installer archive | orkeon / orkeon-slim launchers |
orkeon self-contained, orkeon-slim framework-dependent |
devs who also want the REPL or the service host |
Homebrew β formula in the repository, tap not yet created. installers/homebrew/orkeon.rb
is a binary formula: it downloads the osx tarball matching the machine's architecture
(on_arm / on_intel), installs the payload under the Cellar's libexec, and writes a
bin/orkeon wrapper that points ORKEON_ESBUILD_PATH at the bundled esbuild β the same
contract as wrapper.sh.tmpl. Its test do block runs orkeon doctor rather than
orkeon --version: doctor also runs the bundled esbuild and checks that the native libraries
are in place, and an unconfigured LLM is only a warning there.
version and both url / sha256 pairs are generated, never hand-edited:
scripts/update-homebrew-formula.sh --release <tag> (or --sums <file>) rewrites the five
values from a release's SHA256SUMS and is idempotent. The file in the repository is a template:
it holds the placeholder version 0.0.0 and the literal digests PLACEHOLDER_SHA256_ARM64 /
PLACEHOLDER_SHA256_X64 until a release's sums are written in, so an accidental install fails
verification instead of fetching something unverified.
Publishing the Orkeon/homebrew-tap repository and pushing the formula to it is a release
action, not CI: brew tap orkeon/tap && brew install orkeon does not resolve
before that. Submission to homebrew-core and a .pkg installer stay out of scope until the
project is code-signed.
The apt repository
Debian and Ubuntu users add one source and then manage Orkeon with apt β the user side is Install with apt. The repository lives in this GitHub repository, in two halves:
- The packages stay Release assets β the
.debfilesrelease.ymlalready builds, smokes and attests. Nothing is copied elsewhere. - The signed index lives on the orphan
aptbranch: one directory per channel (InRelease,Release,Release.gpg,Packages,Packages.gz,by-hash/SHA256/β¦), plus the binary keyringorkeon-archive-keyring.gpgat its root for the first setup. Only the workflows push to it, one commit per publication; a ruleset forbids its deletion and any force-push. It holds no.deb, so it weighs a few kilobytes.
The source reads URIs: https://github.com/Orkeon/orkeon/ and Suites: raw/apt/<channel>/ β a
"flat" repository. apt fetches the index at β¦/raw/apt/<channel>/, which GitHub redirects to
raw.githubusercontent.com, and resolves each package's Filename: β
releases/download/<tag>/<asset> β against the same root, so the download lands on the
Release asset. The cost is GitHub's rate limit on anonymous raw traffic (429): apt update
treats it as a warning, a Docker build retries.
| Channel | Directory | Receives |
|---|---|---|
stable |
stable/ |
every v* tag without a pre-release segment β the same test that sets prerelease: on the Release. Final versions only: a release candidate never reaches it |
rc |
rc/ |
every v* tag, so every package of stable is in rc too |
dev |
dev/ |
the orkeon package of every green push to main, versioned <X.Y.Z>~<pre>.dev.<n>; its assets sit on the single fixed-tag prerelease apt-dev; only the three latest builds are kept. Never published to NuGet.org, never attested as a release |
Each channel's Release file keeps Origin: Orkeon and Label: Orkeon for ever (a change
makes every machine confirm it), sets Suite: to the source path without its trailing / and
no Codename (otherwise apt warns "Conflicting distribution"), declares
Architectures: amd64 arm64 and Acquire-By-Hash: yes, lists SHA-256 digests only, carries a
strictly increasing Date (apt ignores an InRelease older than the one it has) and no
Valid-Until. The index is generated by apt-ftparchive; the by-hash files are pruned by the
publishing scripts, keeping at least three generations.
History and immutability. A channel lists every version still attached to a Release, so
apt install orkeon=<version> can always go back β except dev, which keeps its three latest
builds. A stanza, once published, never changes its
digest for the same package, version and architecture: the generator refuses. release.yml
never rewrites the assets of a published tag β it creates the Release as a draft, attaches the
assets, then publishes it, and Releases are immutable β because a re-uploaded asset would make
every machine fail with "Hash Sum mismatch".
The chain on a tag. release publishes the Release; apt-publish (GitHub environment
apt-signing, the only place that holds the signing subkey, as the APT_SIGNING_KEY and
APT_SIGNING_PASSPHRASE secrets, deployable from v* tags and from main, for the dev
channel only) adds the new packages to
rc β and to stable for a final version β, signs the index and pushes the apt branch;
verify-apt then replays the installation block of the guide word for word, in fresh
Debian 12 and 13 and Ubuntu 22.04, 24.04 and 26.04 containers, on amd64 and arm64: install,
upgrade from the previous version, removal in the documented order. It retries while raw
still serves the previous index. A weekly check compares the index with the assets, the key's
expiry with the 180-day threshold, and raw's availability.
The dev chain is apt-dev.yml, started by every CI run that passes on a push to main
(the guard of publish.yml's publish-dev job). It publishes the CLI set for linux-x64 and
linux-arm64 only, packs the two .deb with package-deb.sh --arch, and never calls
dotnet pack, publish.yml or a NuGet feed. The version is publish-dev's, with ~ for - in
the Debian field: <X.Y.Z>~<pre>.dev.<CI run number>, asset orkeon_<X.Y.Z>-<pre>.dev.<n>_<arch>.deb.
Then, in the apt-signing environment, scripts/apt/publish-dev.sh:
- creates the
apt-devprerelease if it is missing (never latest; its tag, set on the first build's commit, never moves); - rebuilds
dev/from the published one, adding the new build and yanking any build that is not among the three newest, and signs it β a build already indexed, or older than the three kept, publishes nothing; - attaches the two packages under their unique names, before the index can point to them; an asset an index already points to is never replaced;
- pushes
dev/to theaptbranch; - deletes the assets of the builds the pushed index does not list β never before.
The keyring package is attached once to apt-dev and its bytes reused afterwards.
workflow_dispatch with publish left false builds the two packages and publishes nothing; with
publish: true, from main, it publishes the newest green CI run of main. apt-dev must exist
before Releases are made immutable: immutability only binds Releases created after it, and an
immutable apt-dev could no longer drop old builds. Its rules are proved without network by
scripts/apt/test-publish-dev.sh in CI, and apt-index.yml upgrades real apt clients from one dev
build to a newer one.
Maintenance outside a tag goes through apt-maintenance.yml (workflow_dispatch, run
from a tag so the environment rule admits it), with the same scripts, environment and
concurrency group as apt-publish: resign signs both channels again with a newer Date;
yank <package>=<version>[/<arch>] withdraws a stanza and signs again; seed <tag>β¦ indexes
assets published before the repository existed.
Procedure: extend or rotate the signing subkey
The subkey is valid two years and is extended at least six months before it expires β CI
fails below 180 days. An expired key breaks apt update on every machine, with no fallback.
- On the offline machine, extend the subkey
(
gpg --quick-set-expire <primary fingerprint> 2y <subkey fingerprint>) β or, to rotate, add a new one (gpg --quick-add-key <primary fingerprint> ed25519 sign 2y). - Export the public certificate, replace
installers/apt/orkeon-archive-keyring.asc, changeinstallers/apt/keyring.version, and update the keyring SHA-256 inSECURITY.md,SECURITY.fr.mdand both installation pages (the CI guard checks they agree). - The next Release publishes the new
orkeon-archive-keyring; users receive it withapt upgrade. An extension stops here; runapt-maintenance.ymlinresignmode if the index should be signed again before the next tag. - For a rotation only, one Release later: the maintainer replaces
APT_SIGNING_KEYwith the new subkey, exported alone (gpg --export-secret-subkeys <subkey fingerprint>!). The old subkey expires, or is revoked.
Procedure: withdraw a version (yank)
- Run
apt-maintenance.ymlinyankmode, from a tag, naming<package>=<version>[/<arch>]. - Check that the channel's
InReleaseon theaptbranch carries a newerDateand no longer lists the version; after anapt update,apt-cache policy orkeonno longer shows it. - Only then, and only if needed, delete the asset from its Release. Any purge of Release assets starts with this procedure β an indexed asset that disappears turns into a 404 for every user.
Procedure: revoke the key
- Publish the revocation certificate (kept offline since the key was created) in
SECURITY.md,SECURITY.fr.mdand the installation pages. - Freeze publication: no tag, no
apt-maintenance.ymlrun, until the new key is in place. - Create a new key and a new keyring, publish their fingerprint and SHA-256 as in the extension procedure, and sign the index with the new subkey. Users must download the new key themselves (the first lines of the installation block) β the only case where they act.
Procedure: the key has expired
Users see EXPKEYSIG on every apt update, and the channel stops updating. Extend the subkey
(procedure above, step 1), publish the certificate and a new orkeon-archive-keyring version,
then run apt-maintenance.yml in resign mode. A machine whose keyring is older than the
extension cannot verify the new index: it reinstalls the keyring by the first lines of the
installation block, or installs the new orkeon-archive-keyring_<YYYY.MM.DD>_all.deb downloaded
from its Release (sudo apt install ./orkeon-archive-keyring_<YYYY.MM.DD>_all.deb).
All flavours are built from the same src/scripting/Orkeon.Scripting.Cli csproj and share
the one bundled esbuild. The remaining CLI
launchers stay framework-dependent β install.sh and install.ps1 detect that case and
print the runtime install commands rather than failing at first launch.
Publish payload. Every
publishofsrc/andexamples/prunes the tree-sitter grammars Orkeon never loads (31 native libraries β 26, on win-x64), viasrc/Directory.Build.targets. Opt out with-p:OrkeonPruneTreeSitterGrammars=false. Every artifact in the table above carries the pruned payload, the MSI included β which also keeps its WiX component GUIDs stable across upgrades.
Build-time / internal (not standalone packages)
| PackageId | Note |
|---|---|
Orkeon.Generators |
Source generator β consumed at build time. GitHub Packages only. |
Orkeon.Host |
IsPackable=false β ships only as the orkeon-host binary in the release archives. |
How publication is wired
- All NuGet packing and pushing lives in
publish.yml(tagv*): the tag/version guard andscripts/check-release-readiness.py(CHANGELOG section cut, PublicAPI shipped), a Release build and the unit + fast tests,dotnet pack Orkeon.slndriven byIsPackable, thescripts/check-package-closure.pygate on the packed artifacts, a push of everything to GitHub Packages with--skip-duplicate(idempotent re-runs), then the NuGet.org lineup (the table above,Orkeonfirst) to NuGet.org. Itspublish-devjob also packs every green push tomain, for GitHub Packages only (see Dev channel above).ci.ymlvalidates (build + test) and packs nothing;release.ymlbuilds the installer archives and the container image, no NuGet packing. - NuGet.org auth is Trusted Publishing (OIDC) β no long-lived API key. A nuget.org
policy (repository
Orkeon/orkeon, workflowpublish.yml) letsNuGet/loginexchange the job's OIDC token for a short-lived key; the steps are gated on theNUGET_USERrepository variable (the nuget.org profile owning the policy). Both are set up and proven β the per-layer pushes went through this path; if the variable ever disappears the steps emit a warning and no-op instead of failing the tag. Expanding the NuGet.org lineup is a maintainer decision recorded in this matrix first (and mirrored incheck-package-closure.py'sLINEUP, the workflow's push loop, the closure-gate arguments and CONTRIBUTING's release process βcheck-doc-claims.pyfails when any copy disagrees), never a workflow edit made in passing. publish.ymlrefuses a tag that does not match thesrc/Directory.Build.propsversion: a tag that re-packs an unchanged props version would make--skip-duplicateskip every push and publish nothing.- Provenance and SBOM. Both workflows attest what they publish with
actions/attest-build-provenance(SLSA v1, signed through Sigstore's public instance and entered in its transparency log):publish.ymlevery*.nupkgof a tag (dev-channel builds are not attested),release.ymlevery archive,.deband MSI. Theghcr.io/orkeon/orkeonimagerelease.ymlpushes to GHCR is not attested. Both generate a CycloneDX SBOM ofOrkeon.slnright after the build (CycloneDXdotnet tool, pinned version, no third-party action) βorkeon-<version>.sbom.cdx.jsonβ and cover it with the same attestation: a release asset next to the archives and a line inSHA256SUMSinrelease.yml, a run artefact namedsbominpublish.yml. How to verify any of it, and why a nuget.org download must shed its repository signature first, is in Verify what you install. - Locked dependency graphs. The packages are built from locked dependency graphs: every
project of
Orkeon.slnoutsideexamples/commits apackages.lock.jsonnext to it (Directory.Build.targets), and CI restores in locked mode (RestoreLockedModeunder theCIvariable), so a restore that would resolve a transitive package differently fails instead of drifting. Two restores are deliberately unlocked: thebuild-test-net11lane (another SDK, to see what it resolves) and every restore with a runtime identifier β the per-RIDdotnet publish -rofpackage-installers.sh/.ps1and ofDockerfile.runners(the committed lock file records the RID-less graph): such a restore writes its own lock file under the project's intermediate folder and never rewrites the committed one. Thedotnet newtemplate content ships no lock file. - Version flows from
src/Directory.Build.props, the single source of truth: no project overrides it, and the publish workflow's tag guard refuses anyv*tag that disagrees with it. The dev channel derives its<X.Y.Z>-<pre>.dev.<n>from it, a build made from a checkout its<version>.local.<stamp>(see Dev channel above).