π«π· 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/orkeonthenorkeon-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(prefixORKEON_,__as section separator), when set, wins over it. AnApiKeywritten${DEEPSEEK_API_KEY}β a placeholder .NET configuration never expands β refuses the start, with the fix.
If you have Docker Model Runner (or another
localhost:12434endpoint) running, the defaultexamples/appsettings/appsettings.jsonneeds 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 1prints 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-llmwrites each exchange in full (request and response, headers and payload) as.jsonlfiles in./logs-llm, created if missing. It turns the log on by itself;--llm-logalone 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):
- The explicit
--settings <path>, if given. appsettings.jsonsitting next to the<config>file.- Walking up the directory tree from the config, looking for an
appsettings/appsettings.jsonsub-directory at each level β that is how the sharedexamples/appsettings/appsettings.jsonprofile matrix is found. - The global per-user config written by
orkeon init(%APPDATA%\Orkeon\appsettings.jsonon 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
- Three ways to run Orkeon β binaries and containers, no source checkout.
- YAML, Builders and CrewFactory β the schema behind every
config.yaml. - Catalog of examples β the 104 bundled examples across 9 themed categories.
- Tool inventory β what the agents can actually do.
- Give your agents a mailbox β an agent that reads, sorts and drafts replies in a real mailbox.