Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

Run your first example (from source)

See also: Three ways to run Orkeon Β· Overview Β· Bootstrap and execution Β· Back to the index

This is the entry point if you have cloned the repository and want to run a bundled crew from source. In about five minutes you will run a real 3-agent example and get a synthesis report back. If you would rather download a prebuilt binary or use a container, see Three ways to run Orkeon.

Fastest path (no build, no clone): docker run -it --rm -e ORKEON_ENTRYPOINT=shell ghcr.io/orkeon/orkeon then orkeon-example run 1 β€” details in Three ways to run Orkeon Β§3.

Prerequisites

Requirement Notes
.NET SDK β‰₯ 10.0.300 The repository pins the SDK in global.json with rollForward: latestFeature. An older SDK fails the build (see Troubleshooting). Verify with dotnet --version.
Git To clone the repository.
An LLM endpoint + key Any of the 16 supported providers, or a local endpoint such as Docker Model Runner / Ollama. Supplied through an appsettings profile (below).

1. Clone and build

git clone https://github.com/Orkeon/orkeon.git
cd orkeon
dotnet build Orkeon.sln

2. Pick an example

Every crew under examples/ is described by a config.yaml. Browse the catalog of examples, or just start with the research assistant β€” a sequential 3-agent crew that scrapes the web, analyses documents, and writes a cited synthesis report:

examples/01-enterprise/01-research-assistant/config.yaml

3. Choose an LLM profile

Runners read their LLM configuration (endpoint, model, API key) from an appsettings.json. The repository ships a profile matrix under examples/appsettings/ so you don't have to hand-write one:

File Target
appsettings.json Default β€” Docker Model Runner at localhost:12434 (no API key)
appsettings.docker-model-runner.local.json.example Docker Model Runner template
appsettings.deepseek.local.json.example DeepSeek cloud
appsettings.openai.local.json.example OpenAI cloud
appsettings.glm.local.json.example / appsettings.glm-medium.local.json.example Z.AI (GLM)
appsettings.gemini.local.json.example Google Gemini
appsettings.grok.local.json.example Grok (x.AI)
appsettings.minimax.local.json.example MiniMax (international endpoint; mainland accounts use api.minimaxi.com)
appsettings.openrouter.local.json.example OpenRouter (aggregator β€” vendor/model ids)
appsettings.mammouth.local.json.example Mammouth AI (aggregator β€” bare vendor ids, reached by its host)
appsettings.local.json.example Generic template β€” points at DeepSeek; switch BaseUrl / Model / ApiKeyEnvVar to any provider

Copy the template that matches your provider, drop it to a real *.local.json (git-ignored), and set your key in the variable it names:

cp examples/appsettings/appsettings.deepseek.local.json.example \
   examples/appsettings/appsettings.deepseek.local.json
export DEEPSEEK_API_KEY=sk-...

A template keeps the key out of the file: its "ApiKeyEnvVar": "DEEPSEEK_API_KEY" names the variable that holds it, which every run reads. ORKEON_Llm__ApiKey (prefix ORKEON_, __ as section separator), when set, wins over it. An ApiKey written ${DEEPSEEK_API_KEY} β€” a placeholder .NET configuration never expands β€” refuses the start, with the fix.

If you have Docker Model Runner (or another localhost:12434 endpoint) running, the default examples/appsettings/appsettings.json needs no key and no copy β€” skip straight to step 4 without --settings.

There is no Provider field to set: the provider is auto-detected from the Llm.BaseUrl in the profile β€” the vendor host, port 11434 for Ollama, otherwise an OpenAI-compatible server (failing a base URL, from the model name, then from the key prefix), so switching providers is just a matter of pointing at the right profile.

4. Run it

Every example runs through the orkeon CLI. From a source checkout, invoke it via its project (no install needed β€” it also picks up your local code changes):

mkdir -p out
dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run \
  examples/01-enterprise/01-research-assistant/config.yaml \
  --settings examples/appsettings/appsettings.deepseek.local.json \
  --mount ./out:/output:rw \
  -v 1

That single command runs the crew end-to-end and exits. The writer agent's file_write tool lands its report on the /output mount, i.e. your local ./out directory.

Installed the CLI? With a release archive or dotnet tool install, the same run is just: orkeon run examples/01-enterprise/01-research-assistant/config.yaml --settings … --mount ./out:/output:rw -v 1.

Follow the run and keep the LLM exchanges

To watch the run in the terminal and keep every request and response sent to the model in a folder of your choice, add --llm-log-path:

dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run \
  examples/01-enterprise/01-research-assistant/config.yaml \
  --settings examples/appsettings/appsettings.deepseek.local.json \
  --mount ./out:/output:rw \
  --llm-log-path ./logs-llm \
  -v 1
  • -v 1 prints what the agents and tools do on the console, and one line per LLM exchange (provider, model, status, duration) once the log is on. It never prints the bodies.
  • --llm-log-path ./logs-llm writes each exchange in full (request and response, headers and payload) as .jsonl files in ./logs-llm, created if missing. It turns the log on by itself; --llm-log alone writes to ./llm-logs.
  • A folder outside the current directory (/tmp/logs, ~/logs) also needs --allow-external-mounts; without it the run stops before calling the model.

The settings section LlmLogging tunes what the files keep (FullEmbeddingLog, LogStreamingExchanges, MaxBodyLengthChars). It is read only with one of the two flags, and no setting chooses the folder. The interactive console orkeon-repl takes the same two flags (CLI reference).

Every flag, explained

The orkeon CLI options you will actually reach for:

Flag Short What it does
<config> (positional) β€” Required (except with --list-tools). The crew definition passed to orkeon run <config> β€” a .yaml file, an .ork.ts scripting file, or a directory holding a multi-file YAML crew. The run verb itself is optional: orkeon <config> does the same.
--settings <path> -s Path to the appsettings.json holding LLM config. Optional β€” see settings resolution.
--verbose <0-2> -v Verbosity. 0 (default) = quiet, 1 = agent and tool activity, plus one summary line per LLM exchange when --llm-log is on, 2 = full debug. The bodies of the exchanges are only in the --llm-log files.
--mount <phys>:<virt>:<rights> -m Expose a host directory to the crew's virtual file system. rights is ro, rw or rwnd (read-write, no delete); ;<subpath>:<rights> segments override the rights below the mount. Several mounts go space-separated after a single flag (--mount a:/x:ro b:/y:rw) β€” the parser rejects a repeated --mount. A crew that writes results needs a :rw mount (/output is the convention that triggers the auto-summary writer).
--mount-id <id> When several Orkeon:FileSystem:Mounts entries of the settings declare the same virtual root, keep the one whose id (the 26-character prefix before its \|) is given. Several ids go space-separated after a single flag.
--allow-external-mounts Permit mounts (and a <config> path or --llm-log-path) located outside the current working directory. Without it, a --mount outside the working directory is refused at start (exit 1); the script's folder and every settings entry in force (one chosen by id included) need no flag. The env var ORKEON_ALLOW_EXTERNAL_MOUNTS=1 enables it for every invocation (the ghcr.io/orkeon/orkeon container image bakes this in).
--var KEY=VALUE -V Inject a variable into the crew input. Task descriptions that contain {KEY} are expanded to VALUE. Several variables go space-separated after a single -V (a repeated flag is rejected). YAML crews only β€” ignored for .ork.ts scripts, which take --inputs.
--initial-context <text> A free-form context string passed to the crew input. YAML crews only β€” ignored for .ork.ts scripts.
--inputs <json> Inline JSON inputs forwarded to a script as the global inputs variable (.ork.ts path).
--inputs-file <path> Same as --inputs, read from a JSON file.
--llm-profile <id> Run on the host LLM profile <id> (Llm:Profiles:<id> in the settings or the ORKEON_ environment) as this run's default: the Llm section becomes that profile, whole. An id the configuration does not define is refused with exit 1 before any host is built β€” see the CLI reference.
--llm-log Capture every LLM HTTP exchange (request + response, headers + payload) as .jsonl under ./llm-logs. The LlmLogging settings tune what is kept.
--llm-log-path <dir> Same as --llm-log, but writes to <dir> (and implies --llm-log). A <dir> outside the working directory needs --allow-external-mounts.
--validate Dry-run: resolve settings, build the host and load the crew (strict tool resolution) without probing the LLM or running anything. Prints VALIDATION OK/FAILED and exits 0 / non-zero. On a .ork.ts the script is first type-checked with tsc when one is found (otherwise WARNING: type check skipped and the rest is validated; TypeCheck: Off skips it). A tool_call deliverable that no agent able to run its task can write prints a WARNING: line on stderr; the exit code is unchanged.
--list-tools Build the host and print the sorted registered tool names, one per line, then exit β€” no crew required.
--events jsonl Emit the versioned JSONL event protocol on stdout instead of plain text (how an external client drives a run) β€” see the run event bus.
--stream With --events, also emit token-by-token llm.delta events (verbose by nature; off unless asked).
--client <name> With --events, the observing peer's hub name (client://<name>, default client).
--memory-limit-mb <n> Jint memory ceiling for a .ork.ts run (overrides appsettings; 0 disables it).

Mounts and the VFS

Orkeon framework code never touches the disk directly β€” all I/O goes through the virtual file system. --mount is how you bridge a host directory into that virtual space:

--mount ./out:/output:rw        # host ./out  ->  virtual /output  (read-write)
--mount ./data:/data:ro         # host ./data ->  virtual /data    (read-only)

The runner automatically mounts the config's own directory read-only, under the name /crew, so the YAML and any sibling data files are always visible β€” a data.csv next to config.yaml is read as /crew/data.csv, never by its path on your disk (ADR-008). Paths outside the working directory require --allow-external-mounts (or ORKEON_ALLOW_EXTERNAL_MOUNTS=1 in the environment β€” the container image's default).

How settings are resolved

When you omit --settings, the runner looks for an appsettings.json in this order (first hit wins):

  1. The explicit --settings <path>, if given.
  2. appsettings.json sitting next to the <config> file.
  3. Walking up the directory tree from the config, looking for an appsettings/appsettings.json sub-directory at each level β€” that is how the shared examples/appsettings/appsettings.json profile matrix is found.
  4. The global per-user config written by orkeon init (%APPDATA%\Orkeon\appsettings.json on Windows, $XDG_CONFIG_HOME/Orkeon/appsettings.json β€” by default ~/.config/Orkeon/appsettings.json β€” on Linux and macOS).

If none is found, the runner falls back to environment variables only and prints a warning. Being explicit with --settings is the most predictable option.

Troubleshooting

Symptoms you may hit on a fresh machine, with the exact message and fix:

Symptom / message Cause Fix
error CS9057: analyzer assembly ... references version 5.3.0 of the compiler .NET SDK older than 10.0.300 Install SDK β‰₯ 10.0.300 (the version pinned in global.json). Check with dotnet --version.
error CS8795: Partial method ... must have an implementation part Source generator did not run β€” usually the same stale-SDK situation as above Upgrade the SDK to β‰₯ 10.0.300 and rebuild.
error NU1008: Projects that use central package version management should not define the version A stray Version= on a PackageReference while Central Package Management is on Remove the inline version; declare it in Directory.Packages.props.
dotnet: command not found (in a script, though dotnet works interactively) dotnet is a shell alias/function not visible to non-interactive shells Put the SDK on PATH in ~/.zprofile / ~/.profile, e.g. export PATH="$HOME/.dotnet:$PATH".
Connection refused (localhost:12434) The default profile targets Docker Model Runner, which isn't running Start Docker Model Runner, or copy a cloud profile (e.g. appsettings.deepseek.local.json) and pass it with --settings.
401 (Unauthorized) or NU1301 during restore, mentioning a nuget.pkg.github.com source A user-level nuget.config declares the GitHub Packages feed (left from an earlier setup, or added for the dev channel) without a valid token Releases don't need it: the Orkeon packages and the orkeon tool are on nuget.org, and the repo's nuget.config pins nuget.org as the only source. Remove the GitHub feed (dotnet nuget remove source <name>) β€” no token is required. Only the dev channel needs it: renew the token (read:packages) with dotnet nuget update source <name> --username <user> --password <PAT> --store-password-in-clear-text.
ERROR: --allow-external-mounts is required ... Your <config> path, a --mount, or --llm-log-path points outside the working directory Add --allow-external-mounts (or set ORKEON_ALLOW_EXTERNAL_MOUNTS=1), or move the paths under the cwd.
WARNING: No appsettings.json found. Using environment variables only. Settings resolution found nothing Pass --settings <path> explicitly (see resolution order).

Next steps