🇬🇧 English version
Trois façons d'exécuter Orkeon
Voir aussi : Lancer votre premier exemple · Vue d'ensemble · Retour à l'index
Les crews Orkeon se lancent de trois façons. Choisissez celle qui correspond à ce que vous acceptez d'installer :
| Voie | Prérequis | Temps avant la première exécution | Idéal pour |
|---|---|---|---|
| 1. Depuis les sources | SDK .NET ≥ 10.0.300, clone git | ~5 min (+ compilation) | Contributeurs, lecture/modification du code, exécution de n'importe lequel des 104 exemples embarqués |
| 2. Binaire de release | Rien pour les paquets CLI (zip/MSI Windows, .deb Debian) — ils embarquent le runtime ; runtime .NET 10 pour les lanceurs supplémentaires de l'archive multi-apps |
~2 min | Exécuter des exemples et des vitrines sans cloner les sources |
| 3. Conteneur | Docker | ~1 min (après le téléchargement de l'image) | CI, exécutions reproductibles, aucun .NET local |
Les trois pilotent le mĂŞme CLI orkeon et acceptent les mĂŞmes flags. La
config de la crew est l'argument positionnel de orkeon run <config> ; les flags
optionnels (--settings, -v, --mount, --var, --llm-log, …) sont documentés une
seule fois, en détail, dans
Lancer votre premier exemple.
1. Depuis les sources
Clonez, compilez, et exécutez n'importe quel config.yaml sous examples/ via
le projet CLI orkeon. Le fichier de settings est à créer : copiez
examples/appsettings/appsettings.deepseek.local.json.example sous le mĂŞme nom sans
.example et mettez-y votre clé (choisir un profil LLM).
git clone https://github.com/Orkeon/orkeon.git
cd orkeon
dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run \
examples/01-enterprise/01-research-assistant/config.yaml \
--settings examples/appsettings/appsettings.deepseek.local.json
C'est la voie la plus souple — elle peut exécuter tous les exemples et prend en compte vos modifications locales. Guide complet, configuration des profils LLM et dépannage : Lancer votre premier exemple.
Ce qu'il faut sur le poste dépend de jusqu'où vous allez :
| Pour… | Il vous faut |
|---|---|
Lancer un exemple (dotnet run, ci-dessus) |
le SDK .NET 10, 10.0.300 ou plus récent (dotnet --version ; global.json l'épingle), et git. Le premier build restaure ses paquets depuis nuget.org |
Construire une archive d'installation depuis le clone (scripts/package-installers.sh, ou scripts/package-installers.ps1 sous Windows), ou installer ce que vous venez de cloner, qui en construit une et vérifie tout cela d'abord |
les deux ci-dessus, plus : Python 3 — python3 sur le PATH, python sous Windows (l'alias du Microsoft Store qui porte ce nom ne compte pas) ; tar ; un accès réseau à nuget.org et à registry.npmjs.org, où le script va chercher le binaire esbuild qu'il embarque. Sous Windows, le script exige PowerShell 7 (pwsh) : Windows PowerShell 5.1, celui qui est installé avec le système, s'y arrête. Sous Linux, le script appelle aussi curl, openssl et sha256sum |
Une archive construite ainsi s'installe comme une archive téléchargée — voir Binaire de release plus bas, prérequis Windows compris.
Installer depuis les sources
dotnet run lance le CLI depuis le clone. Pour avoir sur votre PATH l'orkeon que vous
avez compilé — l'installation que fait une archive de release, à la version de votre
checkout — une commande, depuis le clone :
git clone https://github.com/Orkeon/orkeon.git
cd orkeon
.\scripts\install-from-source.ps1 # Windows, depuis PowerShell 7 (pwsh)
./scripts/install-from-source.sh # Linux, macOS
Le script vérifie d'abord ce dont le build a besoin — la seconde ligne du tableau
ci-dessus — et nomme tout ce qui manque en une fois, avec l'adresse de chaque outil,
avant de compiler quoi que ce soit. Il n'installe rien de tout cela Ă votre place. Il
construit ensuite l'arbre de l'archive du CLI pour votre poste, sans écrire l'archive
(plusieurs minutes ; le premier passage restaure les paquets NuGet et va chercher le binaire
esbuild, un passage suivant ne retélécharge rien de ce qui est en cache), puis l'installe
avec l'installeur de l'archive : %LOCALAPPDATA%\Programs\Orkeon sous Windows, ~/.local
ailleurs.
orkeon --version répond alors la version de votre checkout —
<version>.local.<date du commit> hors tag, jamais le nom d'une release — et
orkeon doctor nomme le canal source.
| Windows | Linux, macOS | |
|---|---|---|
-AppSet full |
--app-set full |
tous les lanceurs — l'hôte de service aussi, et le REPL sous Windows et macOS (le jeu CLI de Linux l'a) — au lieu du seul jeu CLI |
-InstallDir <dossier> |
--prefix <dossier> |
où installer ; --modify-path est passé lui aussi à install.sh |
-WhatIf |
--dry-run |
s'arrêter après les contrôles, et afficher la version et les commandes qu'il lancerait |
-Uninstall |
--uninstall |
retirer l'installation. Ne construit rien ; votre configuration reste |
- Après un
git pull, relancez-le : l'installation est remplacée, et la version suit le commit. - Windows : le build exige PowerShell 7. Lancé depuis Windows PowerShell 5.1, le script le dit, et où le prendre. Si Orkeon est installé par le MSI, ou tourne depuis le répertoire d'installation, l'installeur refuse et le script relaie sa phrase.
- Debian et Ubuntu : le canal
devdu dépôt apt sert les builds demainsans rien compiler sur votre poste. Le script le dit, et continue. - Un clone superficiel (
git clone --depth 1) convient.
Installer le REPL depuis les sources
orkeon-repl, la console interactive, est un programme distinct. Son installation par le
script dépend de votre système :
| Système | Commande, depuis le clone | |
|---|---|---|
| Windows | .\scripts\install-from-source.ps1 -AppSet full |
le jeu par défaut ne contient pas le REPL |
| Linux | ./scripts/install-from-source.sh |
le jeu par défaut le contient |
| macOS | ./scripts/install-from-source.sh --app-set full |
le jeu par défaut ne contient pas le REPL |
Le jeu complet publie tous les lanceurs, l'hôte de service compris : sa compilation prend donc plus de temps. Le jeu par défaut reste sans le REPL sous Windows et macOS parce que le MSI et la formule Homebrew sont construits à partir de lui. Sous Windows et macOS, le script rappelle cette option à la fin de son exécution.
Sous Windows, l'installeur ajoute son dossier bin Ă votre PATH. Sous Linux et macOS,
ajoutez --modify-path si ~/.local/bin n'y est pas déjà . Ouvrez ensuite un nouveau
terminal et lancez orkeon-repl. Il n'a pas de --version : il ouvre directement sa console.
2. Binaire de release
Chaque GitHub Release attache un paquet CLI par plateforme, les archives multi-apps historiques, et un tool dotnet NuGet :
| Artefact | Contenu | Prérequis runtime | Idéal pour |
|---|---|---|---|
orkeon-cli-<version>-win-x64.zip |
le CLI orkeon + install.cmd et install.ps1 |
pas de .NET — autonome. Double-cliquez install.cmd : il tourne sur le PowerShell livré avec Windows. Voir Avant de commencer |
Windows : le téléchargement recommandé |
orkeon-<version>-win-x64.msi |
le même CLI, MSI par utilisateur | pas de .NET — autonome. Non signé : Windows demande avant de le lancer, voir Avant de commencer | Windows, si vous préférez le double-clic et une entrée « Applications installées » |
orkeon_<version>_amd64.deb / _arm64.deb |
le CLI orkeon en /usr/bin/orkeon + le REPL en /usr/bin/orkeon-repl |
aucun — autonome | Debian / Ubuntu — de préférence depuis le dépôt apt, qui sert ces mêmes paquets et leurs mises à jour |
orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz |
le seul CLI orkeon + install.sh (le canal d'onboarding macOS reste CLI seul) |
aucun — autonome | macOS, Apple Silicon et Intel respectivement |
orkeon-<version>-<rid>.tar.gz / .zip |
tous les lanceurs (orkeon, orkeon-repl, orkeon-host…) + install.sh / install.cmd et install.ps1 |
mixte — voir le tableau des commandes ci-dessous | Le REPL et l'hôte de service |
dotnet tool install --global Orkeon.Scripting.Cli |
le seul CLI orkeon — sans esbuild : un script .ork.ts demande npm install -g esbuild (ou ORKEON_ESBUILD_PATH) ; les crews YAML non. orkeon typings écrit les typings d'éditeur |
SDK .NET 10 | Obtenir uniquement le CLI sur un poste qui compile déjà du .NET |
<rid> vaut linux-x64, linux-arm64, osx-x64, osx-arm64 (.tar.gz) ou
win-x64 (.zip). Dans chaque nom de fichier, <version> est la version du tag
— sauf le .deb des deux premières releases à installeurs, nommé avec . à la place du ~ que
porte leur ligne SHA256SUMS : vérifiez ces deux-là à la main. SHA256SUMS couvre tous les artefacts de la release sauf le
MSI, qui a son propre SHA256SUMS.msi (chaque fichier est produit par le job CI
qui a construit l'artefact).
L'archive multi-apps est la seule Ă embarquer plus que le CLI :
| Commande | Ce qu'elle exécute | Runtime |
|---|---|---|
orkeon |
Le CLI principal et le point d'entrée par défaut — orkeon run <config.yaml> pour tout crew YAML, ou orkeon run script.ork.ts pour le DSL de scripting |
autonome |
orkeon-slim |
Le même CLI, dépendant du framework et bien plus petit | requiert .NET 10 |
orkeon-repl |
Console REPL interactive complète (tous les outils intégrés, analyse de code, embeddings locaux) | autonome |
orkeon-host |
Le daemon d'hébergement — enregistre des crews et les sert en continu (unité systemd, service Windows via le script embarqué ou son MSI par machine dédié, passerelle de chat, canal Discord ; voir le service host) | autonome |
Le prérequis runtime, en une ligne. Les paquets CLI (zip, MSI,
.deb), les lanceurorkeonet le REPL embarquent leur propre runtime et n'exigent aucune installation .NET. Tout le reste de l'archive multi-apps (orkeon-slim) — et le tool dotnet — requiert le runtime .NET 10 (à vérifier avecdotnet --list-runtimes).install.shetinstall.ps1détectent le cas et affichent les commandes d'installation de votre plateforme ; ils n'installent jamais de runtime à votre place.
Windows
Deux canaux, tous deux par utilisateur (aucun droit administrateur, rien d'écrit hors de votre profil). Installez un seul canal à la fois — le MSI refuse de s'installer par-dessus une install ZIP, donc désinstallez l'autre d'abord si vous changez.
Avant de commencer
Aucun des deux canaux n'a besoin de .NET. Ce que Windows lui-mĂŞme peut mettre en travers :
- PowerShell. Rien Ă installer. Le zip contient
install.cmd, qui lanceinstall.ps1sur Windows PowerShell 5.1, celui qui est installé avec Windows ;install.ps1est écrit pour lui et pour PowerShell 7 (pwsh). Chaque release installe l'archive sur une vraie machine Windows sous l'un et sous l'autre. - Politique d'exécution. Rien à changer. Un poste Windows qui n'a jamais lancé de script
refuse
.\install.ps1tapé dans PowerShell — « l'exécution de scripts est désactivée sur ce système » — etinstall.cmdest la réponse à cela : il lance le script sous une politique qui ne vaut que pour cette commande et ne change aucun réglage du poste. Ne changez jamais la politique du poste ni celle de votre compte pour installer Orkeon. Si vous lancez le script vous-même, la même politique d'une seule commande s'écritpowershell -ExecutionPolicy Bypass -File .\install.ps1. - Un fichier venu d'Internet. Un zip téléchargé par un navigateur est marqué comme
venant d'Internet, et ce que l'Explorateur en extrait l'est aussi : Windows peut vous
demander de confirmer avant de lancer
install.cmd. La marque n'arrête pas le lanceur. Pour qu'aucune question ne soit posée, levez-la avant d'extraire :Unblock-File .\orkeon-cli-<version>-win-x64.zip. - Une politique imposée par votre organisation (stratégie de groupe) l'emporte sur l'option du lanceur : là , seul un script signé tourne, et l'installeur d'Orkeon ne l'est pas. Voyez votre administrateur, ou passez par un poste où vous avez le droit de lancer des scripts.
- SmartScreen. Aucun des deux MSI n'est signé —
orkeon-<version>-win-x64.msiici, pas plus que celui de l'hôte de service,orkeon-host-<version>-win-x64.msi. Windows affiche « Windows a protégé votre ordinateur » avec un éditeur inconnu : Informations complémentaires → Exécuter quand même. Vérifiez d'abord ce que vous avez téléchargé — sa somme de contrôle et son attestation de build, dans Vérifier ce que vous installez — car l'avertissement ne dit rien du fichier lui-même. Ou passez par le canal ZIP.
Installer
Canal A — le zip (recommandé). Extrayez-le, puis double-cliquez install.cmd : la
fenêtre reste ouverte sur le résultat. Ou depuis un terminal, PowerShell ou cmd :
Expand-Archive orkeon-cli-<version>-win-x64.zip -DestinationPath .
cd orkeon-cli-<version>-win-x64
.\install.cmd # -> %LOCALAPPDATA%\Programs\Orkeon, PATH utilisateur, entrée « Applications installées »
.\install.cmd -Uninstall
install.cmd passe ses arguments Ă install.ps1 (-InstallDir <dossier>, -Uninstall)
et rend son code de sortie. Installer par-dessus une installation la remplace — c'est
ainsi que le canal zip se met Ă jour. Laissez finir une crew en cours d'abord : tant qu'un programme de l'installation tourne, l'installeur refuse, le
nomme, et laisse l'installation comme elle était.
# Canal B — MSI (double-clic, ou en silencieux)
msiexec /i orkeon-<version>-win-x64.msi # même répertoire d'install, même entrée de PATH
msiexec /x orkeon-<version>-win-x64.msi /qn # désinstallation
Dans les deux cas, votre configuration vit dans
%APPDATA%\Orkeon\appsettings.json, et les deux désinstalleurs n'y touchent
pas. (Un appsettings.json laissé dans un répertoire d'installation par une
install antérieure y est migré à la mise à jour.)
Linux
Le dépôt apt est le canal recommandé sur Debian et Ubuntu, amd64 et arm64 :
ajoutez une fois la source signée — le bloc à copier est dans
Installer avec apt — et Orkeon se met à jour avec le reste du
système. Le paquet est autonome, il ne tire donc jamais de paquet dotnet-runtime ni de
dépôt Microsoft :
sudo apt install orkeon orkeon-archive-keyring # installe /usr/bin/orkeon
sudo apt update && sudo apt upgrade # chaque version suivante
Le paquet installe aussi /usr/bin/orkeon-repl, la console interactive qui exécute les
commandes scriptées *.cmd.ts ; elle est autonome, elle aussi.
Sans le dépôt — une machine qui n'atteint pas le contenu brut de GitHub —, installez
directement le .deb d'une release ; il ne reçoit aucune mise à jour :
sudo apt install ./orkeon_<version>_amd64.deb # _arm64.deb sur ARM
sudo apt remove orkeon
(Les deux premières releases à installeurs nomment le fichier avec . à la place du ~ que porte
leur ligne SHA256SUMS : vérifiez ces deux-là à la main.)
Le tar.gz multi-apps + install.sh est l'alternative par utilisateur (et la seule
option quand vous voulez l'hôte de service, ou le REPL sur un système sans apt) :
tar -xzf orkeon-<version>-linux-x64.tar.gz
cd orkeon-<version>-linux-x64
./install.sh # installe dans ~/.local ; --prefix /usr/local pour tout le système
./install.sh --modify-path # ajoute aussi ~/.local/bin Ă vos fichiers rc de shell
./install.sh --uninstall
Comme cette archive embarque des lanceurs dépendant du framework, install.sh
cherche un runtime Microsoft.NETCore.App 10.x (sur le PATH ou sous
DOTNET_ROOT) et, s'il n'en trouve aucun, affiche les commandes exactes de
votre distribution — sudo apt install dotnet-runtime-10.0 sur Ubuntu 25.10+,
l'enregistrement du dépôt packages.microsoft.com sur Debian et Ubuntu LTS, ou
dotnet-install.sh --runtime dotnet --channel 10.0 sous $HOME quand vous
n'avez pas sudo. L'avertissement ne bloque jamais l'installation : les fichiers
sont posés dans tous les cas, et orkeon et orkeon-repl fonctionnent, étant
autonome.
macOS
Aucun prérequis dans les deux cas : les archives CLI macOS sont autonome, aucune installation .NET n'entre en jeu.
Homebrew sera le canal recommandé. La formule vit dans le dépôt, en
installers/homebrew/orkeon.rb, mais le dépôt Orkeon/homebrew-tap n'est
pas encore publié — d'ici là , la commande ci-dessous ne
résout pas, et la voie d'entrée est le tar.gz :
brew tap orkeon/tap # une fois le tap publié
brew install orkeon
Archive + install.sh fonctionne dès aujourd'hui. Prenez osx-arm64 sur
Apple Silicon, osx-x64 sur Intel :
tar -xzf orkeon-cli-<version>-osx-arm64.tar.gz
cd orkeon-cli-<version>-osx-arm64
./install.sh # installe dans ~/.local ; --modify-path pour mettre Ă jour votre rc de shell
./install.sh --uninstall
Gatekeeper. Orkeon n'est pas signé avec un Apple Developer ID, et macOS marque tout ce qui est téléchargé via un navigateur avec
com.apple.quarantine— c'est ce qui produit « impossible d'ouvrir car le développeur ne peut pas être vérifié ».install.shtraite les deux moitiés du problème tout seul : il retire l'attribut de quarantaine de l'arbre installé, et il re-signe en ad-hoc uniquement les fichiers Mach-O embarqués quecodesign -vrejette réellement (une signature d'éditeur valide n'est jamais écrasée). Un téléchargement parcurlne pose aucun attribut de quarantaine, etbrewle retire lui-même. Si une commande est malgré tout tuée ou refusée, l'échappatoire manuelle estxattr -dr com.apple.quarantine ~/.local/lib/orkeon.
Le tar.gz multi-apps (REPL, hĂ´te de service) existe aussi pour
les deux architectures macOS, et requiert le runtime .NET 10 pour les lanceurs
dépendant du framework qu'il embarque — install.sh affiche le
lien de téléchargement
quand il manque.
Premier lancement
Ouvrez un nouveau terminal (pour que la modification du PATH soit prise en compte), puis :
orkeon init # écrit la config globale : quel LLM, quel modèle, quel endpoint
orkeon doctor # vérifie l'installation : runtime, config, profils LLM, joignabilité du LLM, esbuild, tsc, grammaires, …
orkeon run chemin/vers/crew.yaml
orkeon init est un assistant à 5 choix — ollama, docker-model-runner,
openai, custom, ou none — et écrit %APPDATA%\Orkeon\appsettings.json sur
Windows, ~/.config/Orkeon/appsettings.json sur Linux et macOS. Il est
scriptable de bout en bout (--provider, --base-url, --model,
--api-key-env — ou le déconseillé --api-key en clair —, --path, --force,
--no-probe), et c'est ce qu'utilise la CI. orkeon doctor affiche ✅ / ⚠️ / ❌ par vérification, sort en 1 dès qu'une
vérification échoue, et accepte --json pour les scripts.
Aucun LLM configuré ? Orkeon n'échoue pas et ne reste pas muet : il avertit sur stderr — « No
Llmsection configured — falling back to the echo provider … Runorkeon init… » — et exécute la crew contre le fournisseur echo, qui rejoue le prompt au lieu d'y répondre. C'est ce repli qui rend les démos de scripting exécutables sans clé ni serveur ; ce n'est jamais un LLM qui fonctionne. Si vous voyez cet avertissement alors que vous attendiez un vrai modèle, lancezorkeon init, puisorkeon doctorpour confirmer que l'endpoint est joignable.
Exécuter
Le CLI résout les settings LLM exactement comme depuis les sources.
orkeon init couvre le cas courant ; passez --settings pour pointer un profil
précis à la place (voir la
matrice des profils) :
orkeon run chemin/vers/config.yaml \
--settings chemin/vers/appsettings.local.json \
--mount ./out:/output:rw
Les settings sont résolus dans cet ordre : --settings, puis l'appsettings.json
voisin du fichier de config, puis — en remontant les répertoires parents — un
sous-répertoire appsettings/appsettings.json à chaque niveau (la matrice de
profils partagée des exemples), puis le fichier global par utilisateur écrit par orkeon init, puis les
variables d'environnement ORKEON_* seules.
Une crew peut aussi ĂŞtre un dossier. Pointez
orkeon run sur un répertoire contenant une crew multi-fichiers — config.yaml
pour les réglages de la crew, un agent par fichier sous agents/, une task par
fichier sous tasks/, le nom de chaque fichier servant d'identifiant — et il se
charge exactement comme un fichier YAML unique. Le triplet plat
(crew.yaml + agents.yaml + tasks.yaml) est également accepté, et toutes les
options se comportent Ă l'identique sur un dossier (--settings, -V/--var,
--initial-context, --mount, --validate, --verbose, --llm-log) :
orkeon run examples/crew-multifile --validate
# VALIDATION OK: …/examples/crew-multifile (agents=2, tasks=2, tools resolved=0)
Un dossier contenant à la fois une disposition YAML et un point d'entrée de
scripting — n'importe quel *.ork.ts ou *.ork.js posé directement dedans, quel
que soit son nom — est refusé, en nommant les deux candidats, tout comme un dossier
sans disposition reconnue : Orkeon ne devine jamais lequel vous vouliez. Voir
YAML et builders pour la disposition elle-mĂŞme.
Une crew peut nommer les dossiers qu'elle utilise. Un bloc mounts: dans
config.yaml (ou crew.yaml) liste les racines virtuelles que la crew lit et écrit —
/output, ou <ulid>|/output pour épingler une entrée des settings quand plusieurs
déclarent cette racine (une entrée des settings peut porter un identifiant de
26 caractères devant son |). orkeon run crew/ résout alors le bloc face au fichier de settings sans aucun
--mount, et refuse en une ligne une racine absente ou ambiguë ; --mount-id <ulid>
choisit une entrée depuis la ligne de commande, et un simple
--mount <dossier>:/output:rw remplace toutes les entrées des settings de cette racine
pour le run.
Vous pouvez aussi exécuter une commande directement depuis l'archive extraite,
sans installer : ./libexec/orkeon/orkeon run ….
3. Conteneur
L'image ghcr.io/orkeon/orkeon (construite depuis Dockerfile.runners,
publiée sur GHCR) a le CLI orkeon comme point d'entrée par défaut, embarque le
REPL (orkeon-repl) à côté plus les 104 exemples fournis — zéro .NET local
requis. L'hĂ´te de service n'y est pas : il a sa propre image, construite depuis
deploy/Dockerfile.host (voir l'hĂ´te de service).
L'image publiée est multi-plateforme : un seul tag, linux/amd64 et linux/arm64, et Docker
tire celle de votre machine. Sur Apple Silicon, ou tout hĂ´te arm64, elle tourne en
natif, sans émulation. docker manifest inspect ghcr.io/orkeon/orkeon:<version>
liste les deux.
Chaque image garde la licence et les notices de ce qu'elle redistribue sous
/usr/share/doc/orkeon/ (LICENSE.md, THIRD-PARTY-NOTICES.md), le chemin du paquet
Debian ; le runtime .NET est celui de l'image de base de Microsoft, qui porte les siennes.
La convention /workspace
Montez votre répertoire de projet sur /workspace et référencez tout depuis là .
Un seul volume, aucun flag supplémentaire :
docker run --rm -v "$PWD:/workspace" ghcr.io/orkeon/orkeon \
run /workspace/crews/my-crew/config.yaml \
--settings /workspace/appsettings.local.json \
--mount /workspace/data:/data:ro /workspace/output:/output:rw
Trois commodités de l'image rendent cela immédiat :
- Pas besoin de
--allow-external-mounts— l'image fixeORKEON_ALLOW_EXTERNAL_MOUNTS=1, parce que la frontière du conteneur met déjà en bac à sable tous les chemins atteignables (passez-e ORKEON_ALLOW_EXTERNAL_MOUNTS=0pour rétablir le garde-fou). - Les écritures fonctionnent — l'entrypoint adopte l'uid/gid propriétaire
de
/workspaceavant de s'exécuter, donc la crew peut écrire dans votre bind mount et les fichiers créés vous appartiennent sur l'hôte. Pas de--user, pas dechmod. (Il reste non privilégié : sans montage, il retombe sur l'utilisateur non-rootappde l'image. Undocker run --userexplicite contourne cette adoption, et-e ORKEON_STAY_ROOT=1garde root.) /workspaceexiste toujours — même sans rien monter, pour que les mêmes commandes fonctionnent en CI.
Les montages de volumes sont la façon dont le système de fichiers hôte atteint
le VFS de la crew : le -v de Docker associe
hôte → conteneur, le flag --mount associe conteneur → chemins virtuels de la
crew (/data, /output, …).
Exécuter un exemple embarqué
Les exemples sont livrés dans l'image sous /app/examples, avec un utilitaire
qui rend leur exécution immédiate. La session la plus simple possible :
# une fois, sur l'hôte : récupérer le modèle par défaut (Docker Desktop → Model Runner)
docker model pull ai/granite-4.0-h-tiny
docker run -it --rm -e ORKEON_ENTRYPOINT=shell -v "$PWD/out:/output" \
ghcr.io/orkeon/orkeon
# puis, dans le shell :
orkeon-example list # parcourir les 104 exemples embarqués
orkeon-example run 1 # exécuter le n°1 (assistant de recherche)
orkeon-example show 42 # lire d'abord le README d'un exemple
orkeon-example settings # quels settings LLM s'appliquent, et pourquoi
orkeon-example run résout le numéro vers sa config, monte /output pour les
résultats fichiers, et choisit les settings LLM pour vous (section suivante). Quand
un numéro existe dans deux catégories (16, 102), il liste les candidats —
qualifiez avec la catégorie : orkeon-example run 02/16 (une sous-chaîne du nom,
comme research-assistant, marche aussi ; les arguments qui suivent l'identifiant
vont Ă orkeon run).
Settings LLM dans le conteneur — le défaut intégré vise Docker Model
Runner sur votre hĂ´te (host.docker.internal:12434) : le docker model pull
ci-dessus est la seule mise en place, et tous les exemples fonctionnent ensuite
sans aucun flag. Si vous l'oubliez, orkeon-example run échoue vite, avant la
crew, en affichant la commande docker model pull exacte (et, quand l'endpoint sert
d'autres modèles, la surcharge -e ORKEON_Llm__Model=<name> pour en utiliser
un — docker model list sur l'hôte montre ce que vous avez). Pour utiliser
autre chose, choisissez un profil dans /etc/orkeon/profiles avec
ORKEON_LLM_PROFILE :
-e ORKEON_LLM_PROFILE= |
Endpoint | Nécessite |
|---|---|---|
(non défini) = host-dmr |
Docker Model Runner sur l'hĂ´te, :12434 |
docker model pull … sur l'hôte |
host-ollama |
Ollama sur l'hĂ´te, :11434 |
ollama pull llama3.2 sur l'hĂ´te |
openai |
Cloud OpenAI | -e ORKEON_Llm__ApiKey=sk-… |
local |
modèle embarqué dans l'image | la variante d'image local-llm (ci-dessous) |
Les variables d'environnement ORKEON_Llm__* surchargent n'importe quel profil
(ex. -e ORKEON_Llm__Model=…). Sur un moteur Linux nu (sans Docker Desktop),
ajoutez --add-host=host.docker.internal:host-gateway pour que les profils hĂ´te
résolvent.
Fenêtre de contexte plus grande (modèles hôte) — Docker Model Runner sert chaque modèle avec sa taille de contexte par défaut. Sur les versions récentes de Docker Desktop, vous pouvez l'augmenter par modèle, par exemple 128K pour Gemma 4 :
docker model configure --context-size 131072 gemma4:latest # voir : docker model configure --help
docker model configure show gemma4:latest # vérifier — list/inspect ne montrent que le packaging
Un gros cache KV est gourmand en RAM (plusieurs Go supplémentaires à 128K) —
dimensionnez l'hôte en conséquence. Llm.MaxTokens dans les settings Orkeon
plafonne la longueur de la réponse et est indépendant de la taille de contexte
côté serveur.
Tout ce qui touche aux modèles locaux (pièges de DMR, Ollama, changement de modèle, dimensionnement du contexte, dépannage) est consolidé dans le guide des modèles locaux.
Aucun modèle du tout ? Les démos de scripting embarquées tournent sur le repli
LLM echo — pas de clé, pas de serveur, pas de réseau. L'exécution l'annonce sur
stderr (« No Llm section configured — falling back to the echo provider … Run
orkeon init … »), donc un conteneur non configuré n'est jamais pris pour un
modèle qui fonctionne :
orkeon run /app/examples/scripting/01-hello-world.ork.ts
Tout en local : embarquer un modèle dans votre image
Construisez une variante qui n'exige ni serveur de modèle côté hôte, ni clé
d'API — le llama-server de llama.cpp plus un GGUF sont embarqués et servis
dans le conteneur sur la même forme d'URL que celle qu'utilisent déjà les
settings par défaut. Cette variante est linux/amd64 seulement — le llama.cpp
embarqué est un build x64 — : sur une machine arm64, ajoutez --platform linux/amd64
au docker build (elle tourne alors sous émulation, lentement) :
# Granite 4.0 h-tiny (Apache 2.0, ~4,2 Go de poids → image ~6 Go)
docker build -f Dockerfile.runners --target local-llm \
--build-arg LOCAL_MODEL_URL=https://huggingface.co/ibm-granite/granite-4.0-h-tiny-GGUF/resolve/main/granite-4.0-h-tiny-Q4_K_M.gguf \
-t orkeon:granite .
# Gemma 4 E4B avec un contexte de 128K (licence Gemma — gardez l'image locale, ne la poussez pas)
docker build -f Dockerfile.runners --target local-llm \
--build-arg LOCAL_MODEL_URL=https://huggingface.co/unsloth/gemma-4-E4B-it-qat-GGUF/resolve/main/gemma-4-E4B-it-qat-UD-Q4_K_XL.gguf \
--build-arg LOCAL_MODEL_NAME=ai/gemma4 \
--build-arg LOCAL_MODEL_CTX=131072 \
-t orkeon:gemma4 .
# LOCAL_MODEL_CTX fixe la taille de contexte de llama-server (défaut 8192) ; surchargez
# par exécution avec -e ORKEON_LOCAL_LLM_CTX=… — à 128K, prévoyez plusieurs Go de RAM.
docker run -it --rm -m 8g -e ORKEON_ENTRYPOINT=shell orkeon:granite
# le modèle se charge au démarrage (30-90 s), puis :
orkeon-example run 1
Inférence CPU : comptez environ 5 à 15 tokens/s et donnez de la mémoire au
conteneur (-m 8g ; sous WSL2, augmentez la mémoire de la VM dans .wslconfig
si nécessaire). -e ORKEON_LOCAL_LLM=0 saute le serveur embarqué. Ces variantes
sont à construire soi-même par conception — aucun tag pré-construit n'est
publié, donc les obligations de licence des modèles restent de votre côté du
mur.
Le coup unique (sans shell) fonctionne toujours — le point d'entrée est
orkeon :
docker run --rm \
-v "$PWD/out:/output" \
ghcr.io/orkeon/orkeon \
run examples/01-enterprise/01-research-assistant/config.yaml \
--mount /output:/output:rw
Autres exécutables et shell interactif
Le point d'entrée est orkeon, donc tout ce qui suit le nom de l'image est
un argument du CLI (run <config> …). Pour lancer un autre exécutable, définissez
la variable d'environnement ORKEON_ENTRYPOINT — orkeon (la valeur par défaut),
repl ou shell ; toute autre valeur est refusée avec une ligne d'usage :
docker run -it --rm -e ORKEON_ENTRYPOINT=repl \
-v "$PWD:/workspace" \
-v "$PWD/appsettings.local.json:/app/appsettings.local.json:ro" \
ghcr.io/orkeon/orkeon --settings /app/appsettings.local.json
Tout ce qui suit le nom de l'image va au REPL, qui ne lit ses réglages que depuis
--settings (un fichier monté n'est pas lu de lui-même), comme hors de Docker. L'image lui
monte /workspace en lecture-écriture, le projet que vous y liez : un --mount sur
/workspace, ou un fichier --settings qui déclare Orkeon:FileSystem:Mounts, remplace ce
montage par défaut. Sans --settings, le REPL tourne sur le provider echo et le signale.
Il n'y a pas d'exécutable par famille d'exemples : les crews finance sont des
scripts main.ork.ts qu'exécute la même CLI orkeon, comme tous les autres
exemples.
docker run --rm \
-v "$PWD/appsettings.local.json:/app/appsettings.local.json:ro" \
ghcr.io/orkeon/orkeon \
run examples/03-finance-trading/31-algo-trading/main.ork.ts \
--settings /app/appsettings.local.json
ORKEON_ENTRYPOINT=shell ouvre un zsh interactif dans l'image (en démarrant
dans /workspace) — pratique pour fouiller les exemples embarqués ou déboguer
des montages. Une bannière d'accueil liste les commandes et chemins disponibles
(supprimez-la avec -e ORKEON_NO_BANNER=1), et chaque exécutable est sur le PATH
sous les mĂŞmes noms que dans les archives de release (orkeon,
orkeon-repl, …) :
docker run -it --rm -e ORKEON_ENTRYPOINT=shell -v "$PWD:/workspace" \
ghcr.io/orkeon/orkeon
# orkeon /workspace % orkeon-example run 1
# orkeon /workspace % orkeon run /workspace/crews/my-crew/config.yaml --validate
L'image embarque git : un crew qui le lance par shell_command travaille sur le
dépôt monté sur /workspace. Comme partout ailleurs, shell_command ne laisse par défaut
un crew lancer que git status, git log, git diff et git show ; toute autre
commande git (rev-parse, add, commit, push) demande
Orkeon:Tools:Shell:AllowInterpreters, que l'image ne fixe pas
(Sécurité). Tout répertoire est déclaré sûr pour git dans
l'image (safe.directory) : un dépôt dont le propriétaire sur l'hôte n'est pas
l'utilisateur du conteneur est lu quand même — git exécute alors aussi les hooks et la
configuration de ce dépôt sans vérifier à qui il appartient. Un commit demande en plus une
identité : passez GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME et
GIT_COMMITTER_EMAIL avec -e, l'image n'en fixe aucune.
Laquelle choisir ?
- Vous voulez juste voir tourner une crew ? Prenez un binaire de release
(voie 2) ou le conteneur (voie 3) et pointez
orkeon runsur n'importe quelconfig.yaml.- Sur Windows :
orkeon-cli-<version>-win-x64.zip+install.cmd, ou le MSI si vous préférez le double-clic. Un canal à la fois. - Sur Debian / Ubuntu : le dépôt apt, puis
sudo apt install orkeon orkeon-archive-keyring. - Puis
orkeon init→orkeon doctor→orkeon run.
- Sur Windows :
- Vous voulez le REPL ou l'hĂ´te de service ? Le REPL est dans le paquet Debian et
Ubuntu (
/usr/bin/orkeon-repl) et dans l'archive multi-apps (voie 2) ; l'hôte de service est dans l'archive. Tous deux sont autonomes : aucun runtime .NET à installer. - Vous modifiez Orkeon ou exécutez des exemples arbitraires ? Depuis les sources (voie 1).
- CI / reproductible / aucune chaîne d'outils locale ? Conteneur (voie 3).
Quel que soit votre choix, les flags et l'histoire des profils appsettings
sont identiques — lisez-les une fois dans
Lancer votre premier exemple.
Mettre Ă jour Orkeon
Mettre Ă jour, c'est installer la version plus rĂ©cente par le canal qui a servi Ă
l'installation. Vos réglages ne font partie d'aucune installation : l'appsettings.json
écrit par orkeon init reste où il est, quel que soit le canal mis à jour.
Vous ne savez plus quel canal c'était ? orkeon doctor vous le dit : sa ligne
install-channel nomme le canal par lequel cette installation est passée et la commande qui
le met Ă jour. orkeon --version --verbose imprime le mĂŞme canal sur une ligne Ă part, pour
un script.
| Installé avec | Passer à la dernière release |
|---|---|
| Le tool dotnet | dotnet tool update -g Orkeon.Scripting.Cli |
| Des paquets NuGet, dans un projet | dotnet add package Orkeon — et Orkeon.Tools si le projet le référence — réécrit la version |
| Zip Windows, archive tar.gz macOS ou Linux | Extraire la nouvelle archive et lancer son install.cmd / install.sh : il supprime l'installation précédente et met la nouvelle à sa place. Sous Windows, laisser finir une crew en cours d'abord : l'installeur refuse tant qu'un programme de l'installation tourne |
| MSI Windows | Lancer le nouveau MSI : il remplace celui qui est installé, y compris entre deux pré-releases |
| Le dépôt apt | sudo apt update && sudo apt upgrade |
| Un paquet Debian téléchargé | sudo apt install ./orkeon_<version>_amd64.deb (_arm64.deb sur ARM) — ou passer au dépôt apt, qui se met à jour seul |
| Conteneur | docker pull ghcr.io/orkeon/orkeon — :latest avance à chaque release |
| Depuis les sources | git pull ; le prochain dotnet run recompile. Une installation faite depuis le clone : git pull, puis relancer scripts/install-from-source |
orkeon --version affiche ensuite la version qui tourne : orkeon <version>. Une installation dont le canal ne peut être déterminé répond unknown.
Suivre main : le canal dev
Entre deux releases, chaque commit validé par la CI sur main est publié en
<X.Y.Z>-<pre>.dev.<n> — n étant le numéro de ce run de CI — sur le flux Orkeon de GitHub
Packages, où le suivant le remplace. La numérotation et l'élagage des versions sont décrits
dans la
matrice de publication.
Ce canal couvre les surfaces NuGet : le tool orkeon, le tool orkeon-repl (paquet
Orkeon.ConsoleApp) et les paquets. Sous Debian et Ubuntu, le paquet orkeon suit aussi
main, par le canal apt dev — voir
Installer avec apt. Les autres
installeurs et l'image conteneur ne sont construits que sur les tags.
Créez un jeton. GitHub Packages en exige un même pour lire un paquet public : un personal access token (classic) avec le scope
read:packages— le créer ici.Déclarez le flux, une fois. Lancez cette commande, comme toutes celles de cette section, depuis un répertoire hors de tout clone de ce dépôt : dans un clone, son
nuget.configgarde nuget.org comme unique source, et vous obtiendriez la dernière release à la place.dotnet nuget add source https://nuget.pkg.github.com/Orkeon/index.json \ --name orkeon-github \ --username <votre-utilisateur-github> \ --password <PAT-avec-read:packages> --store-password-in-clear-textdotnet nuget add source https://nuget.pkg.github.com/Orkeon/index.json --name orkeon-github --username <votre-utilisateur-github> --password <PAT-avec-read:packages>Windows chiffre le jeton. Linux et macOS ne le peuvent pas, d'où le flag : le jeton est alors stocké tel quel dans
~/.nuget/NuGet/NuGet.Config.Installez, puis mettez à jour. La mise à jour vous amène au
mainle plus récent à chaque exécution :dotnet tool install -g Orkeon.Scripting.Cli # la première fois dotnet tool update -g Orkeon.Scripting.Cli # toutes les fois suivantesNuGet garde la liste des versions d'un flux pendant 30 minutes : juste après une fusion, ajoutez
--no-http-cachepour voir le nouveau build.Vérifiez.
orkeon --versionafficheorkeon <X.Y.Z>-<pre>.dev.<n>. Le run#<n>du workflow CI donne le commit, et la section[Unreleased]du CHANGELOG liste ce qui a changé depuis la dernière release. Le site de documentation suit les tags : pour un build dev, lisez la documentation surmain.
Déjà installé par un paquet — le .deb, le zip, le MSI, une archive tar.gz ? Deux orkeon se
trouvent alors sur la machine, et c'est le premier du PATH qui s'exécute. Sous Linux, le
/usr/bin/orkeon du .deb passe en général avant ~/.dotnet/tools : orkeon continue donc
de lancer la release. command -v orkeon (PowerShell : Get-Command orkeon) montre lequel
répond ; désinstallez le paquet, ou appelez ~/.dotnet/tools/orkeon explicitement.
Dans un projet, faites flotter la version plutôt que de l'épingler :
<PackageReference Include="Orkeon" Version="*-*" /> (et de mĂŞme pour Orkeon.Tools), puis
dotnet restore --force-evaluate (avec --no-http-cache juste après une fusion) pour passer au
build le plus récent. En gestion centrale des paquets, la version flottante va dans
Directory.Packages.props et exige
<CentralPackageFloatingVersionsEnabled>true</CentralPackageFloatingVersionsEnabled> — sans
ce réglage, la restauration échoue avec NU1011. Un épinglage exact sur un build dev — un
manifeste de tools, un packages.lock.json en mode verrouillé — casse dès que le build
suivant le remplace ; un simple Version="<X.Y.Z>-<pre>.dev.<n>" se restaure encore, sur le
build suivant, avec l'avertissement NU1603. Épinglez une release pour tout ce qui doit durer.
Revenir aux releases :
dotnet nuget remove source orkeon-github # ou `dotnet nuget disable source orkeon-github`, pour garder le jeton
dotnet tool update -g Orkeon.Scripting.Cli --version <release> --allow-downgrade
<release> est un tag de la page des releases
sans son v initial. Tant que le flux reste déclaré, --prerelease et les versions
flottantes résolvent le build dev de tous les paquets Orkeon, ceux de NuGet.org compris ;
--version épingle une release.