π«π· Version franΓ§aise
Three ways to run Orkeon
See also: Run your first example Β· Overview Β· Back to the index
Orkeon crews can be launched three ways. Pick the one that matches how much you want to install:
| Way | Prerequisites | Time to first run | Best for |
|---|---|---|---|
| 1. From source | .NET SDK β₯ 10.0.300, git clone | ~5 min (+ build) | Contributors, reading/modifying code, running any of the 104 bundled examples |
| 2. Release binary | Nothing for the CLI packages (Windows zip/MSI, Debian .deb) β they bundle the runtime; .NET 10 runtime for the extra launchers in the multi-app archive |
~2 min | Running examples and showcases without a source checkout |
| 3. Container | Docker | ~1 min (after image pull) | CI, reproducible runs, no local .NET at all |
All three drive the same orkeon CLI and accept the same flags. The crew
config is the positional argument to orkeon run <config>; the option flags (--settings, -v,
--mount, --var, --llm-log, β¦) are documented once, in detail, in
Run your first example.
1. From source
Clone, build, and run any config.yaml under examples/ through the orkeon
CLI project. The settings file is yours to create: copy
examples/appsettings/appsettings.deepseek.local.json.example to the same name without
.example and put your key in it (choose an LLM profile).
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
This is the most flexible path β it can run every example and picks up your local code changes. Full walkthrough, LLM-profile setup, and troubleshooting: Run your first example.
What the machine needs depends on how far you go:
| To⦠| You need |
|---|---|
Run an example (dotnet run, above) |
the .NET 10 SDK, 10.0.300 or later (dotnet --version; global.json pins it), and git. The first build restores its packages from nuget.org |
Build an installer archive from the clone (scripts/package-installers.sh, or scripts/package-installers.ps1 on Windows), or install what you just cloned, which builds one and checks all of this first |
the two above, plus: Python 3 β python3 on the PATH, python on Windows (the Microsoft Store alias of that name does not count); tar; network access to nuget.org and to registry.npmjs.org, where the script fetches the esbuild binary it bundles. On Windows the script needs PowerShell 7 (pwsh): Windows PowerShell 5.1, the one installed with the system, stops on it. On Linux the script also calls curl, openssl and sha256sum |
An archive built this way is installed like a downloaded one β see Release binary below, its Windows prerequisites included.
Install from source
dotnet run runs the CLI from the clone. To have the orkeon you built on your PATH β
the installation a release archive makes, at the version of your checkout β one command,
from the clone:
git clone https://github.com/Orkeon/orkeon.git
cd orkeon
.\scripts\install-from-source.ps1 # Windows, from PowerShell 7 (pwsh)
./scripts/install-from-source.sh # Linux, macOS
The script first checks what the build needs β the second row of the table above β and
names everything that is missing in one go, with where to get it, before it compiles
anything. It installs none of it for you. It then builds the tree of the CLI archive for
your machine, without writing the archive (several minutes; the first run restores NuGet
packages and fetches the esbuild binary, a later one downloads nothing that is cached), and
installs it with the archive's own installer: %LOCALAPPDATA%\Programs\Orkeon on Windows,
~/.local elsewhere.
orkeon --version then answers the version of your checkout β
<version>.local.<commit date> off a tag, never the name of a release β and
orkeon doctor names the channel source.
| Windows | Linux, macOS | |
|---|---|---|
-AppSet full |
--app-set full |
every launcher β the service host too, and the REPL on Windows and macOS (the Linux CLI set has it) β instead of the CLI set |
-InstallDir <folder> |
--prefix <dir> |
where to install; --modify-path also goes through to install.sh |
-WhatIf |
--dry-run |
stop after the checks, and print the version and the commands it would run |
-Uninstall |
--uninstall |
remove the installation. Builds nothing; your configuration stays |
- After a
git pull, run it again: the installation is replaced, and the version moves with the commit. - Windows: the build needs PowerShell 7. Started from Windows PowerShell 5.1, the script says so, and where to get it. If Orkeon is installed through the MSI, or running from the install directory, the installer refuses and the script relays its sentence.
- Debian and Ubuntu: the apt repository's
devchannel serves the builds ofmainwithout a build on your machine. The script says so, and carries on. - A shallow clone (
git clone --depth 1) works.
Install the REPL from source
orkeon-repl, the interactive console, is a separate program. Whether the script installs
it depends on your system:
| System | Command, from the clone | |
|---|---|---|
| Windows | .\scripts\install-from-source.ps1 -AppSet full |
the default set leaves the REPL out |
| Linux | ./scripts/install-from-source.sh |
the default set has it |
| macOS | ./scripts/install-from-source.sh --app-set full |
the default set leaves the REPL out |
The full set publishes every launcher, the service host included, so it takes longer to build. The default set stays without the REPL on Windows and macOS because the MSI and the Homebrew formula are built from it. On Windows and macOS, the script reminds you of this option when it ends.
On Windows the installer puts its bin folder on your PATH. On Linux and macOS, add
--modify-path if ~/.local/bin is not already there. Then open a new terminal and start
orkeon-repl. It has no --version: it opens its console directly.
2. Release binary
Each GitHub Release attaches a per-platform CLI package, the historical multi-app archives, and a NuGet dotnet tool:
| Artifact | What's inside | Runtime prerequisite | Best for |
|---|---|---|---|
orkeon-cli-<version>-win-x64.zip |
the orkeon CLI + install.cmd and install.ps1 |
no .NET β self-contained. Double-click install.cmd: it runs on the PowerShell Windows ships. See Before you start |
Windows: the recommended download |
orkeon-<version>-win-x64.msi |
the same CLI, per-user MSI | no .NET β self-contained. Not code-signed: Windows asks before it runs it, see Before you start | Windows, if you'd rather double-click and get an "Installed apps" entry |
orkeon_<version>_amd64.deb / _arm64.deb |
the orkeon CLI at /usr/bin/orkeon + the REPL at /usr/bin/orkeon-repl |
none β self-contained | Debian / Ubuntu β best installed from the apt repository, which serves these same packages and their updates |
orkeon-cli-<version>-osx-arm64.tar.gz / -osx-x64.tar.gz |
the orkeon CLI alone + install.sh (the macOS onboarding channel stays CLI-only) |
none β self-contained | macOS, Apple Silicon and Intel respectively |
orkeon-<version>-<rid>.tar.gz / .zip |
every launcher (orkeon, orkeon-repl, orkeon-hostβ¦) + install.sh / install.cmd and install.ps1 |
mixed β see the command table below | The REPL and the service host |
dotnet tool install --global Orkeon.Scripting.Cli |
the orkeon CLI β without esbuild: a .ork.ts script needs npm install -g esbuild (or ORKEON_ESBUILD_PATH); YAML crews do not. orkeon typings writes the editor typings |
.NET 10 SDK | Getting just the CLI on a dev box that already builds .NET |
<rid> is linux-x64, linux-arm64, osx-x64, osx-arm64 (.tar.gz) or
win-x64 (.zip). In every file name, <version> is the tag's version β except the .deb
of the two earliest releases with installers, named with . in place of the ~ their SHA256SUMS line
reads: check those two by hand.
SHA256SUMS covers every artifact of the release except the MSI, which
has its own SHA256SUMS.msi (each file is produced by the CI job that built the artifact).
The multi-app archive is the only one that carries more than the CLI:
| Command | What it runs | Runtime |
|---|---|---|
orkeon |
The main CLI and default entry point β orkeon run <config.yaml> for any YAML crew, or orkeon run script.ork.ts for the scripting DSL |
self-contained |
orkeon-slim |
The same CLI, framework-dependent and much smaller | needs .NET 10 |
orkeon-repl |
Full interactive REPL console (all built-in tools, code analysis, local embeddings) | self-contained |
orkeon-host |
The service host daemon β registers crews and serves them long-running (systemd unit, Windows service via the bundled script or its own per-machine MSI, chat gateway, Discord channel; see the service host) | self-contained |
Runtime prerequisite, in one line. The CLI packages (zip, MSI,
.deb), theorkeonlauncher and the REPL bundle their own runtime and need no .NET install at all. Everything else in the multi-app archive (orkeon-slim) β and the dotnet tool β needs the .NET 10 runtime (verify withdotnet --list-runtimes).install.shandinstall.ps1detect the case and print the install commands for your platform; they never install a runtime for you.
Windows
Two channels, both per-user (no administrator rights, nothing written outside your profile). Install one channel at a time β the MSI refuses to install over a ZIP install, so uninstall the other one first if you switch.
Before you start
Neither channel needs .NET. What Windows itself may put in the way:
- PowerShell. Nothing to install. The zip carries
install.cmd, which startsinstall.ps1on Windows PowerShell 5.1, the one installed with Windows;install.ps1is written for it and for PowerShell 7 (pwsh). Every release installs the archive on a real Windows machine under both. - Execution policy. Nothing to change. A Windows machine that has never run a script
refuses
.\install.ps1typed in PowerShell β "running scripts is disabled on this system" β andinstall.cmdis the answer to that: it runs the script under a policy that holds for that one command and changes no setting of the machine. Never change the policy of the machine or of your account to install Orkeon. Should you run the script yourself, the same one-command policy ispowershell -ExecutionPolicy Bypass -File .\install.ps1. - A file from the Internet. A zip downloaded by a browser is marked as coming from
the Internet, and so is what Explorer extracts from it: Windows may ask you to confirm
before it runs
install.cmd. The mark does not stop the launcher. To have no question asked, lift it before extracting:Unblock-File .\orkeon-cli-<version>-win-x64.zip. - A policy your organization sets (Group Policy) overrules the launcher's option: there, only a signed script runs, and Orkeon's installer is not signed. Ask your administrator, or use a machine where you are allowed to run scripts.
- SmartScreen. Neither MSI is code-signed β
orkeon-<version>-win-x64.msihere, nor the service host'sorkeon-host-<version>-win-x64.msi. Windows shows "Windows protected your PC" with an unknown publisher: More info β Run anyway. Check what you downloaded first β its checksum and its build attestation, in Verify what you install β since the warning says nothing about the file itself. Or use the ZIP channel.
Install
Channel A β the zip (recommended). Extract it, then double-click install.cmd: the
window stays open on the result. Or from a terminal, PowerShell or cmd:
Expand-Archive orkeon-cli-<version>-win-x64.zip -DestinationPath .
cd orkeon-cli-<version>-win-x64
.\install.cmd # -> %LOCALAPPDATA%\Programs\Orkeon, user PATH, "Installed apps" entry
.\install.cmd -Uninstall
install.cmd passes its arguments to install.ps1 (-InstallDir <folder>,
-Uninstall) and returns its exit code. Installing over an installation replaces it β
that is how the zip channel updates. Let a running crew finish first: while a program of the installation is running, the installer refuses,
names it, and leaves the installation as it was.
# Channel B β MSI (double-click, or silently)
msiexec /i orkeon-<version>-win-x64.msi # same install dir, same PATH entry
msiexec /x orkeon-<version>-win-x64.msi /qn # uninstall
Either way, your configuration lives in %APPDATA%\Orkeon\appsettings.json, and
both uninstallers leave it alone. (An appsettings.json left behind in an
install directory by an earlier install is migrated there on upgrade.)
Linux
The apt repository is the recommended channel on Debian and Ubuntu, amd64 and
arm64: add the signed source once β the block to copy is in
Install with apt β and Orkeon updates with the rest of the
system. The package is self-contained, so it never pulls a dotnet-runtime package or a
Microsoft repository:
sudo apt install orkeon orkeon-archive-keyring # installs /usr/bin/orkeon
sudo apt update && sudo apt upgrade # every later version
The package also installs /usr/bin/orkeon-repl, the interactive console that runs the
*.cmd.ts scripted commands; it is self-contained too.
Without the repository β a machine that cannot reach GitHub's raw content β install one
release's .deb directly; it receives no updates:
sudo apt install ./orkeon_<version>_amd64.deb # _arm64.deb on ARM
sudo apt remove orkeon
(The two earliest releases with installers name the file with . in place of the ~ their
SHA256SUMS line reads: check those two by hand.)
The multi-app tar.gz + install.sh is the per-user alternative (and the only
option when you want the service host, or the REPL on a system without apt):
tar -xzf orkeon-<version>-linux-x64.tar.gz
cd orkeon-<version>-linux-x64
./install.sh # installs to ~/.local; --prefix /usr/local for system-wide
./install.sh --modify-path # also appends ~/.local/bin to your shell rc files
./install.sh --uninstall
Because that archive carries framework-dependent launchers, install.sh checks
for a Microsoft.NETCore.App 10.x runtime (on the PATH or under DOTNET_ROOT)
and, if it finds none, prints the exact commands for your distribution β
sudo apt install dotnet-runtime-10.0 on Ubuntu 25.10+, the
packages.microsoft.com repository registration on Debian and Ubuntu LTS, or
dotnet-install.sh --runtime dotnet --channel 10.0 under $HOME when you have
no sudo. The warning never blocks the install: the files land either way, and
orkeon and orkeon-repl still run, being self-contained.
macOS
No prerequisite either way: the macOS CLI tarballs are self-contained, so no .NET install is involved.
Homebrew will be the recommended channel. The formula lives in the
repository at installers/homebrew/orkeon.rb, but the Orkeon/homebrew-tap
repository is not published yet β until
then the command below does not resolve, and the tar.gz route is the way in:
brew tap orkeon/tap # once the tap is published
brew install orkeon
Tarball + install.sh works today. Pick osx-arm64 on Apple Silicon,
osx-x64 on Intel:
tar -xzf orkeon-cli-<version>-osx-arm64.tar.gz
cd orkeon-cli-<version>-osx-arm64
./install.sh # installs to ~/.local; --modify-path to update your shell rc
./install.sh --uninstall
Gatekeeper. Orkeon is not signed with an Apple Developer ID, and macOS tags anything downloaded through a browser with
com.apple.quarantineβ which is what produces "cannot be opened because the developer cannot be verified".install.shhandles both halves of that on its own: it clears the quarantine attribute from the installed tree, and it ad-hoc re-signs only the bundled Mach-O files thatcodesign -vactually rejects (a valid publisher signature is never overwritten). Downloading withcurlsets no quarantine attribute in the first place, andbrewstrips it itself. If a command is still killed or refused afterwards, the manual escape hatch isxattr -dr com.apple.quarantine ~/.local/lib/orkeon.
The multi-app tar.gz (REPL, service host) is available for
both macOS architectures too, and needs the .NET 10 runtime for the
framework-dependent launchers it carries β install.sh prints the
download link when it is
missing.
First run
Open a new terminal (so the PATH change is picked up), then:
orkeon init # writes the global config: which LLM, which model, which endpoint
orkeon doctor # checks the install: runtime, config, LLM profiles, LLM reachability, esbuild, tsc, grammars, β¦
orkeon run path/to/crew.yaml
orkeon init is a 5-choice wizard β ollama, docker-model-runner, openai,
custom, or none β and writes %APPDATA%\Orkeon\appsettings.json on Windows,
~/.config/Orkeon/appsettings.json on Linux and macOS. It is scriptable end to
end (--provider, --base-url, --model, --api-key-env β or the discouraged inline
--api-key β, --path, --force, --no-probe), which is what CI uses. orkeon doctor prints β
/ β οΈ / β per
check, exits 1 as soon as one check fails, and takes --json for scripts.
No LLM configured? Orkeon does not fail and does not go quiet: it warns on stderr β "No
Llmsection configured β falling back to the echo provider β¦ Runorkeon initβ¦" β and runs the crew against the echo provider, which replays the prompt instead of answering it. That fallback is what makes the scripting demos runnable with no key and no server; it is never a working LLM. If you see that warning when you expected a real model, runorkeon init, thenorkeon doctorto confirm the endpoint is reachable.
Run
The CLI resolves LLM settings the same way as from source. orkeon init covers
the common case; pass --settings to point at a specific profile instead (see
the profile matrix):
orkeon run path/to/config.yaml \
--settings path/to/appsettings.local.json \
--mount ./out:/output:rw
Settings are resolved in order: --settings, then appsettings.json sitting
next to the config file, then β walking up the parent directories β an
appsettings/appsettings.json sub-directory at each level (the shared examples
profile matrix), then the
global per-user file written by orkeon init, then ORKEON_* environment
variables alone.
A crew can also be a directory. Point orkeon run at a
folder holding a multi-file crew β config.yaml for the crew settings, one agent
per file under agents/, one task per file under tasks/, each file name being
the entity id β and it loads exactly like a single YAML file. The flat
triplet (crew.yaml + agents.yaml + tasks.yaml) is accepted too, and every
option behaves identically on a directory (--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)
A directory holding both a YAML layout and a scripting entry point β any *.ork.ts
or *.ork.js sitting directly in it, whatever the file is called β is refused, naming
both candidates, and so is a directory with no recognized layout: Orkeon never guesses
which one you meant. See
YAML and builders for the layout itself.
A crew can name the folders it uses. A mounts: block in config.yaml (or
crew.yaml) lists the virtual roots the crew reads and writes β /output, or
<ulid>|/output to pin one settings entry when several declare that root (a settings
entry may carry a 26-character id before its |). orkeon run crew/ then resolves the block
against the settings file with no --mount at all, and refuses in one line when a root is
missing or ambiguous;
--mount-id <ulid> picks an entry from the command line, and a plain
--mount <folder>:/output:rw replaces every settings entry of that root for the run.
You can also run a command straight from the extracted archive without
installing: ./libexec/orkeon/orkeon run β¦.
3. Container
The ghcr.io/orkeon/orkeon image (built from Dockerfile.runners,
published to GHCR) has the orkeon CLI as its default entry point, ships the
REPL (orkeon-repl) next to it plus the 104 bundled examples β zero local
.NET required. The service host is not in it: it has its own image, built from
deploy/Dockerfile.host (see the service host).
The published image is multi-platform: one tag, linux/amd64 and linux/arm64, and Docker
pulls the one that matches your machine. On Apple Silicon, or any arm64 host, it runs
natively, not under emulation. docker manifest inspect ghcr.io/orkeon/orkeon:<version>
lists both.
Every image keeps the license and the notices of what it redistributes under
/usr/share/doc/orkeon/ (LICENSE.md, THIRD-PARTY-NOTICES.md), the path the Debian
package uses; the .NET runtime is the one of Microsoft's base image, which carries its own.
The /workspace convention
Mount your project directory at /workspace and reference everything from
there. One volume, no extra flags:
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
Three image conveniences make this Just Work:
- No
--allow-external-mountsneeded β the image bakesORKEON_ALLOW_EXTERNAL_MOUNTS=1, because the container boundary already sandboxes every reachable path (pass-e ORKEON_ALLOW_EXTERNAL_MOUNTS=0to restore the guard). - Writes just work β the entrypoint adopts the uid/gid that owns
/workspacebefore running, so the crew can write to your bind mount and the files it creates belong to you on the host. No--user, nochmod. (It still runs unprivileged: when nothing is mounted it falls back to the image's non-rootappuser. An explicitdocker run --userbypasses the adoption, and-e ORKEON_STAY_ROOT=1keeps root.) /workspacealways exists β even with nothing mounted, so the same commands work in CI.
Volume mounts are how the host filesystem reaches the crew's
VFS: the Docker -v maps host β container,
the --mount flag maps container β the crew's virtual paths (/data,
/output, β¦).
Running a bundled example
The examples ship inside the image under /app/examples, along with a helper
that makes running them a one-liner. The simplest possible session:
# one-time, on the host: pull the default model (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
# then, inside the shell:
orkeon-example list # browse the 104 bundled examples
orkeon-example run 1 # run #1 (research assistant)
orkeon-example show 42 # read an example's README first
orkeon-example settings # which LLM settings apply, and why
orkeon-example run resolves the number to its config, mounts
/output for file results, and picks LLM settings for you (next section). When
a number exists in two categories (16, 102), it lists the candidates β
qualify with the category: orkeon-example run 02/16 (a name substring such as
research-assistant works too; extra arguments after the id go to orkeon run).
LLM settings inside the container β the baked default targets Docker
Model Runner on your host (host.docker.internal:12434): the
docker model pull above is the only setup, and every example then works with
zero flags. Forget it and orkeon-example run fails fast before the crew,
printing the exact pull command (and, when the endpoint serves other models,
the -e ORKEON_Llm__Model=<name> override to use one of them β
docker model list on the host shows what you have). To use something else,
pick a profile from /etc/orkeon/profiles with ORKEON_LLM_PROFILE:
-e ORKEON_LLM_PROFILE= |
Endpoint | Needs |
|---|---|---|
(unset) = host-dmr |
Docker Model Runner on the host, :12434 |
docker model pull β¦ on the host |
host-ollama |
Ollama on the host, :11434 |
ollama pull llama3.2 on the host |
openai |
OpenAI cloud | -e ORKEON_Llm__ApiKey=sk-β¦ |
local |
model embedded in the image | the local-llm image variant (below) |
ORKEON_Llm__* env vars override any profile (e.g. -e ORKEON_Llm__Model=β¦).
On a plain Linux engine (no Docker Desktop), add
--add-host=host.docker.internal:host-gateway so the host profiles resolve.
Bigger context window (host models) β Docker Model Runner serves each model with its default context size. On recent Docker Desktop versions you can raise it per model, e.g. 128K for Gemma 4:
docker model configure --context-size 131072 gemma4:latest # see: docker model configure --help
docker model configure show gemma4:latest # verify β list/inspect only show packaging metadata
A large KV cache is RAM-hungry (several extra GB at 128K) β size the host
accordingly. Llm.MaxTokens in the Orkeon settings caps the response length
and is independent of the server-side context size.
Everything local-model related (DMR pitfalls, Ollama, model switching, context sizing, troubleshooting) is consolidated in the Local models guide.
No model at all? The bundled scripting demos run on the echo LLM fallback β no
key, no server, no network. The run announces it on stderr ("No Llm section
configured β falling back to the echo provider β¦ Run orkeon init β¦"), so an
unconfigured container is never mistaken for a working model:
orkeon run /app/examples/scripting/01-hello-world.ork.ts
Fully local: bake a model into your image
Build a variant that needs no host-side model server and no API key β
llama.cpp's llama-server plus one GGUF are embedded and served inside the
container on the same URL shape the default settings already use. This variant is
linux/amd64 only β the embedded llama.cpp build is x64 β so on an arm64 machine add
--platform linux/amd64 to the docker build (it then runs under emulation, slowly):
# Granite 4.0 h-tiny (Apache 2.0, ~4.2 GB of weights β ~6 GB image)
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 with a 128K context (Gemma license β keep the image local, don't push it)
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 bakes the llama-server context size (default 8192); override
# per run with -e ORKEON_LOCAL_LLM_CTX=β¦ β at 128K plan several extra GB of RAM.
docker run -it --rm -m 8g -e ORKEON_ENTRYPOINT=shell orkeon:granite
# the model loads at startup (30-90 s), then:
orkeon-example run 1
CPU inference: expect roughly 5β15 tokens/s and give the container memory
(-m 8g; on WSL2, raise the VM memory in .wslconfig if needed).
-e ORKEON_LOCAL_LLM=0 skips the embedded server. These variants are
build-your-own by design β no pre-built tag is published, so model-license
obligations stay on your side of the wall.
One-shot (no shell) still works β the entry point is 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
Other executables and the interactive shell
The entry point is orkeon, so everything after the image name is CLI
arguments (run <config> β¦). To start a different executable, set the
ORKEON_ENTRYPOINT env var β orkeon (the default), repl or shell; any other
value is rejected with a usage line:
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
Everything after the image name goes to the REPL, which reads its settings only from
--settings (a mounted file is not read on its own), as outside Docker. The image mounts
/workspace read-write for it, the project you bind there: a --mount on /workspace, or a
--settings file declaring Orkeon:FileSystem:Mounts, replaces that default. Without
--settings the REPL runs on the echo provider and says so.
There is no executable per example family: the finance crews are main.ork.ts
scripts the same orkeon CLI runs, like every other example.
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 opens an interactive zsh inside the image (starting
in /workspace) β handy for poking at the bundled examples or debugging mounts.
A welcome banner lists the available commands and paths (suppress it with
-e ORKEON_NO_BANNER=1), and every executable is on the PATH under the same names
as the release archives (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
The image carries git: a crew that runs it through shell_command works on the
repository mounted on /workspace. As anywhere else, shell_command lets a crew run only
git status, git log, git diff and git show by default; any other git command
(rev-parse, add, commit, push) needs Orkeon:Tools:Shell:AllowInterpreters, which
is not set in the image (Security). Every directory is
declared safe to git inside the image (safe.directory), so a repository whose owner on
the host is not the user the container runs as is read all the same - git then also runs
the hooks and the configuration of that repository without checking who owns it. A commit
needs an identity as well: pass GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL,
GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL with -e, the image sets none.
Which one should I use?
- Just want to see a crew run? Grab a release binary (way 2) or the container
(way 3) and point
orkeon runat anyconfig.yaml.- On Windows:
orkeon-cli-<version>-win-x64.zip+install.cmd, or the MSI if you prefer double-clicking. One channel at a time. - On Debian / Ubuntu: the apt repository, then
sudo apt install orkeon orkeon-archive-keyring. - Then
orkeon initβorkeon doctorβorkeon run.
- On Windows:
- Want the REPL or the service host? The REPL is in the Debian and Ubuntu package
(
/usr/bin/orkeon-repl) and in the multi-app archive (way 2); the service host is in the archive. Both are self-contained: no .NET runtime to install. - Modifying Orkeon or running arbitrary examples? Run from source (way 1).
- CI / reproducible / no local toolchain? Container (way 3).
Whichever you choose, the flags and the appsettings profile story are identical
β read them once in Run your first example.
Update Orkeon
Updating is installing the newer version through the channel you installed with. Your
settings are not part of any install: the appsettings.json that orkeon init wrote stays
where it is, whichever channel you update.
Not sure which channel that was? orkeon doctor tells you: its install-channel line
names the channel this install came through and the command that updates it.
orkeon --version --verbose prints the same channel on a line of its own, for a script.
| Installed with | Move to the latest release |
|---|---|
| The dotnet tool | dotnet tool update -g Orkeon.Scripting.Cli |
| NuGet packages, in a project | dotnet add package Orkeon β and Orkeon.Tools if the project references it β rewrites the version |
| Windows zip, macOS or Linux tarball | Extract the new archive and run its install.cmd / install.sh: it deletes the previous install and puts the new one in its place. On Windows, let a running crew finish first: the installer refuses while a program of the installation is running |
| Windows MSI | Run the new MSI: it replaces the installed one, between two pre-releases too |
| The apt repository | sudo apt update && sudo apt upgrade |
| A downloaded Debian package | sudo apt install ./orkeon_<version>_amd64.deb (_arm64.deb on ARM) β or move to the apt repository, which updates by itself |
| Container | docker pull ghcr.io/orkeon/orkeon β :latest moves with each release |
| From source | git pull; the next dotnet run rebuilds. An installation made from the clone: git pull, then run scripts/install-from-source again |
orkeon --version then prints the version that runs: orkeon <version>. An install whose channel cannot be determined answers unknown.
Follow main: the dev channel
Between two releases, every commit CI validates on main is published as
<X.Y.Z>-<pre>.dev.<n> β n being the number of that CI run β to the Orkeon feed on GitHub
Packages, where the next one replaces it. How the versions are numbered and pruned is in the
publication matrix.
The channel reaches the NuGet channels: the orkeon tool, the orkeon-repl tool
(package Orkeon.ConsoleApp) and the packages. On Debian and Ubuntu, the orkeon package
follows main too, through the apt dev channel β see
Install with apt. The other
installers and the container image are built from tags alone.
Create a token. GitHub Packages asks for one even to read a public package: a personal access token (classic) with the
read:packagesscope β create it here.Declare the feed, once. Run this command, and every other one in this section, from a directory outside any clone of this repository: inside one, its
nuget.configkeeps nuget.org as the only source, and you would get the last release instead.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-textdotnet nuget add source https://nuget.pkg.github.com/Orkeon/index.json --name orkeon-github --username <your-github-username> --password <PAT-with-read:packages>Windows encrypts the token. Linux and macOS cannot, hence the flag: the token is then stored as is in
~/.nuget/NuGet/NuGet.Config.Install, then update. The update takes you to the newest
maineach time you run it:dotnet tool install -g Orkeon.Scripting.Cli # the first time dotnet tool update -g Orkeon.Scripting.Cli # every time afterNuGet keeps a feed's version list for 30 minutes: right after a merge, add
--no-http-cacheto see the new build.Check.
orkeon --versionprintsorkeon <X.Y.Z>-<pre>.dev.<n>. Run#<n>of the CI workflow names the commit, and the[Unreleased]section of the CHANGELOG lists what changed since the last release. The documentation site follows the tags: for a dev build, read the documentation onmain.
Already installed from a package β the .deb, the zip, the MSI, a tarball? Two orkeon
now sit on the machine, and the first one on PATH is the one that runs. On Linux, the
.deb's /usr/bin/orkeon usually comes before ~/.dotnet/tools, so orkeon keeps running
the release. command -v orkeon (PowerShell: Get-Command orkeon) shows which one answers;
uninstall the package, or call ~/.dotnet/tools/orkeon explicitly.
In a project, float the version rather than pin it:
<PackageReference Include="Orkeon" Version="*-*" /> (and the same for Orkeon.Tools), then
dotnet restore --force-evaluate (with --no-http-cache right after a merge) to move to the
newest build. Under central package management the floating version goes in
Directory.Packages.props and needs
<CentralPackageFloatingVersionsEnabled>true</CentralPackageFloatingVersionsEnabled> β
without it, restore fails with NU1011. An exact pin on a dev build β a tool manifest, a
packages.lock.json in locked mode β breaks as soon as the next build replaces it; a plain
Version="<X.Y.Z>-<pre>.dev.<n>" still restores, onto the next build, with warning NU1603. Pin a
release for anything that has to last.
Back to the releases:
dotnet nuget remove source orkeon-github # or `dotnet nuget disable source orkeon-github`, to keep the token
dotnet tool update -g Orkeon.Scripting.Cli --version <release> --allow-downgrade
<release> is a tag of the releases page
without its leading v. As long as the feed stays declared, --prerelease and floating
versions resolve the dev build for every Orkeon package, the NuGet.org ones included;
--version pins a release.