🇫🇷 Version française

Orkeon

AI agent teams that stay inside the lines — every file, endpoint and budget an agent may touch is declared, then enforced. Described in YAML, TypeScript (.ork.ts) or C#; one .NET runtime executes all three.

---

The problem

You let a coding agent loose on a repository. It reads what it needs, then writes — a file two directories up, a ~/.config it had no business in, a /tmp script it runs next. Nothing stopped it because nothing was there to stop it: the agent's tools called File.WriteAllText on whatever path the model produced.

Orkeon puts the boundary in front of the model, not behind it:

• A virtual file system. Agents only ever see virtual paths (/workspace, /output); each one is a mount you declared, with the rights you gave it (ro/rw). A path outside a mount is refused before any byte lands on disk.
• A sandbox for code, an execution budget for autonomy — tool calls, depth, wall time, tokens, spawned agents — and circuit breakers for loops. The agent runs out of permission before it runs out of ideas.
• A Roslyn analyzer for your own code. Orkeon.Compliance.Vfs is a standalone NuGet package with no Orkeon dependency: add it to any C# project and every direct System.IO call is a compile error — the line an agent (or a colleague) would have slipped in does not build.

Around that boundary sits a complete agent-team framework: crews of agents with roles, goals and tools, six orchestration strategies (sequential, hierarchical, parallel, consensual, graph, autonomous), 16 LLM providers, memory, RAG, semantic code analysis — typed end to end, Clean Architecture, .NET 10.

Try it in two minutes — no API key

A local model, one agent, one writable mount. From a clone of this repository (git clone --depth 1 https://github.com/Orkeon/orkeon && cd orkeon), with Ollama installed and the .NET 10 SDK:

ollama pull qwen2.5:1.5b
dotnet tool install -g Orkeon.Scripting.Cli --prerelease
mkdir -p out && orkeon run examples/quickstart/crew.yaml --mount ./out:/output:rw

The tool comes from nuget.org — no extra feed, no token. The agent writes ./out/hello.md — and only there: /output is the single mount, rw. Change the crew's task to write anywhere else and watch the file-system service refuse it. The block above is executed literally by CI on every change (Quickstart workflow): if it stops working, the build goes red before you find out. Everything about local models — Docker Model Runner, Ollama, a model baked into the container image — is in the local models guide.

To update the tool later: dotnet tool update -g Orkeon.Scripting.Cli --prerelease. To follow main between two releases, and for every other channel, see Update Orkeon.

Forge a team from a need

You do not have to write the crew. Describe the need; orkeon forge interviews you, drafts the team, renders it (YAML or .ork.ts), validates it, runs it in a sandbox, diagnoses the run and asks for your verdict — then promotes the result into your project when you say so:

orkeon init                                  # once: pick a provider and a model (Ollama included)
orkeon forge "a team that triages the issues of a GitHub repository every morning"
orkeon forge list                            # every session on disk, resumable
orkeon forge promote <slug> --to ./crews     # adopt the crew that passed

The cycle is brief → blueprint → render → validate → test → diagnose → verdict, with sessions you can resume, edit and re-test. It needs a configured model: without one it stops at the door with FORGE-LLM-UNAVAILABLE and points you to orkeon init. Walkthrough: Forge a team from a need.

---

Quick Start — one crew, three ways

The same crew, written at three levels of abstraction. Pick the one that fits — or mix them: they all run on the same .NET execution engine.

1. Declarative YAML — no code, no build: edit the file, run it again (crew.yaml):

name: "research-crew"
goal: "Research AI trends for 2026"
process: "sequential"

agents:
  researcher:
    role: "Researcher"
    goal: "Find and summarize information about AI trends"
    verbose: true

tasks:
  research:
    description: "Search for the latest AI developments and trends"
    expectedOutput: "A comprehensive summary report"
    agent: "researcher"

orkeon run crew.yaml

2. Programmatic TypeScript — scripting ergonomics (agent bodies, hooks, dynamic spawning, FSM/graph literals), .NET runtime underneath — and still no rebuild: scripts are transpiled on the fly (crew.ork.ts):

/// <reference orkeon-script="1.0" />

const researcher = agentBuilder()
    .name("researcher").role("Researcher")
    .goal("Find and summarize information about AI trends")
    .build();

const research = taskBuilder()
    .name("research")
    .agent(researcher)
    .description("Search for the latest AI developments and trends")
    .expectedOutput("A comprehensive summary report")
    .build();

const crew = crewBuilder()
    .name("research-crew")
    .goal("Research AI trends for 2026")
    .process("sequential")
    .withAgent(researcher)
    .withTask(research)
    .build();

globalThis.crew = crew;   // hand the crew to the runner, which drives its tasks

orkeon run crew.ork.ts

How a script ends picks its engine: globalThis.crew = crew runs the tasks, await crew.run() runs the agents' own .body() code and ignores every task — see Write a crew in TypeScript.

3. Pure C# — the builder API embedded in your own application, strongly typed end-to-end:

using Orkeon.Domain.Agent;
using Orkeon.Domain.Crew;

var agent = new AgentBuilder()
    .Role("Researcher")
    .Goal("Find and summarize information about AI trends")
    .Verbose()
    .Build();

var crew = new CrewBuilder()
    .Goal("Research AI trends for 2026")
    .Sequential()
    .WithAgent(agent)
    .WithTask(t => t
        .Description("Search for the latest AI developments and trends")
        .ExpectedOutput("A comprehensive summary report"))
    .Build();

// wire the host and kick it off — see docs/getting-started/bootstrap.md

No API key? Run everything on a model on your own machine (Docker Model Runner, Ollama, or a model embedded in the container image) — see the Local models guide. Full walkthroughs: Three ways to run Orkeon · Run your first example.

---

Installation

Clone without --recursive. This repository declares private maintainer submodules: they are not available in a public clone. Nothing in the build, the tests or the contribution workflow needs them, and a failing git submodule update on those paths is expected and harmless — see CONTRIBUTING.md.

Windows — download orkeon-cli-<version>-win-x64.zip (or the .msi) from the releases; it is self-contained, no .NET needed:

# Verify the download first: every release ships a SHA256SUMS asset (SHA256SUMS.msi for the .msi)
(Get-FileHash orkeon-cli-<version>-win-x64.zip -Algorithm SHA256).Hash.ToLower()
Select-String -Path SHA256SUMS -Pattern 'win-x64\.zip'   # the two hashes must match

Expand-Archive orkeon-cli-<version>-win-x64.zip -DestinationPath .; cd orkeon-cli-<version>-win-x64
.\install.ps1        # or: msiexec /i orkeon-<version>-win-x64.msi -- pick one channel, not both
orkeon init          # in a NEW terminal: pick your LLM provider and model
orkeon run crew.yaml

Debian / Ubuntu — download orkeon_<version>_amd64.deb; self-contained too, no dotnet-runtime package pulled in:

# SHA256SUMS is a release asset too — download it alongside the .deb and check
grep " orkeon_<version>_amd64.deb$" SHA256SUMS | sha256sum --check   # expect: OK

sudo apt install ./orkeon_<version>_amd64.deb
orkeon init          # writes ~/.config/Orkeon/appsettings.json
orkeon run crew.yaml

macOS — Homebrew becomes the recommended route once the Orkeon/homebrew-tap repository ships with the first tagged release:

brew tap orkeon/tap && brew install orkeon    # once the tap is published
orkeon init
orkeon run crew.yaml

Until then (and on any machine), the self-contained tarball — osx-arm64 for Apple Silicon, osx-x64 for Intel. install.sh clears the Gatekeeper quarantine attribute for you:

# The asset name carries the version, and GitHub's `latest/download/` shortcut skips
# prereleases — so resolve the newest tag first (or copy the asset link off the
# releases page, which is the same thing done by hand).
TAG=$(curl -fsSL https://api.github.com/repos/Orkeon/orkeon/releases | grep -m1 '"tag_name"' | cut -d'"' -f4)
VER=${TAG#v}; BASE=https://github.com/Orkeon/orkeon/releases/download/$TAG

curl -fsSL -O "$BASE/orkeon-cli-$VER-osx-arm64.tar.gz"     # osx-x64 on Intel
curl -fsSL -O "$BASE/SHA256SUMS"
grep " orkeon-cli-$VER-osx-arm64.tar.gz$" SHA256SUMS | shasum -a 256 --check -   # expect: OK

tar -xzf "orkeon-cli-$VER-osx-arm64.tar.gz" && cd "orkeon-cli-$VER-osx-arm64" && ./install.sh
orkeon init

orkeon doctor checks the install (runtime, config, LLM reachability, esbuild, grammars) whenever something looks off.

---

Features

Every number below is recomputed from the tree on each CI run — bash scripts/count-surface.sh prints them next to the rule that counts them, and a README that disagrees fails the build.

---

Architecture

Orkeon follows Clean Architecture with three concentric layers:

+----------------------------------------------------------+
|  Infrastructure  (outer)                                 |
|  LLM providers, memory stores, tools, HTTP clients       |
|                                                          |
|  +------------------------------------------------+      |
|  |  Application  (middle)                         |      |
|  |  Use cases, orchestrators, service interfaces  |      |
|  |                                                |      |
|  |  +----------------------------------------+   |      |
|  |  |  Domain  (inner)                       |   |      |
|  |  |  Agents, Crews, Tasks, Tools, LLMs     |   |      |
|  |  |  Pure business logic, one satellite of constants  |   |      |
|  |  +----------------------------------------+   |      |
|  +------------------------------------------------+      |
+----------------------------------------------------------+

• Domain: Core entities and value objects (Agent, Crew, CrewTask, IBaseTool, ILlmProvider). No external dependencies.
• Application: Use cases and orchestration logic. Defines interfaces (ports) implemented by Infrastructure.
• Infrastructure: LLM providers, memory stores, tool implementations, and all external integrations.

Around the core, dedicated projects cover hosting (Orkeon.Hosting, plus the orkeon-host service daemon of Orkeon.Host and the orkeon run --events jsonl run event bus), plugins (Orkeon.Plugins), Roslyn source generators (Orkeon.Generators), the VFS-compliance analyzer (Orkeon.Compliance.Vfs — a standalone NuGet package with no Orkeon dependency: <PackageReference Include="Orkeon.Compliance.Vfs" PrivateAssets="all" /> makes direct System.IO a compile error in any C# project), the TypeScript-syntax scripting DSL (Orkeon.Scripting plus the orkeon CLI tool), the tool families (Orkeon.Tools.*, shipped together as the Orkeon.Tools package), and the RaggableTree semantic code-analysis engine (Orkeon.Analysis, shipped inside the Orkeon package).

---

Documentation

These pages, together with the generated API reference, are published as a browsable site at https://orkeon.github.io/orkeon/. docs.yml deploys it on every v* tag, so the site goes live with the first tagged release and always documents a tagged version.

---

Why Orkeon?

• Three authoring surfaces, one engine — the same crew can be a YAML file an analyst edits, a TypeScript script a developer iterates on (both run with zero rebuild), or C# embedded in your product. No rewrite when you graduate from one to the next.
• Orchestration beyond pipelines — six strategies, including a graph mode backed by a LangGraph-style StateGraph engine (conditional edges and controlled cycles in its C# API) and an autonomous mode where a manager assigns the work, a failed task is handed to a peer, and agents talk over an A2A channel, all under a multi-dimensional execution budget (tool calls, depth, wall time, tokens, spawns).
• Batteries included — 91 tools, 16 LLM providers, 6 memory stores, vision, RAG, code analysis: usable out of the box, replaceable through Clean Architecture ports.
• Local-first — every example runs against a model on your own machine (Docker Model Runner, Ollama, or llama.cpp embedded in the container image). No API key required to evaluate it.
• The boundary is the product — a rights-audited virtual filesystem in front of every file access, a Roslyn analyzer that refuses raw System.IO in your own code, execution budgets and circuit breakers for autonomy, checkpoint and resume for long runs. Rate limiting, monitoring and the rest are one AddOrkeonXxx() away.
• Typed all the way down — no Dictionary<string, object> plumbing; source generators keep the typed surface boilerplate-free.

---

Project Status

The current version is 1.0.0-rc.4 on .NET 10 — the V1 release candidate (src/Directory.Build.props is the single source of truth; the Release badge above and git tag say what is tagged). Recent milestones: the NuGet distribution consolidated into a single Orkeon package (plus Orkeon.Tools and a few opt-ins — see the publication matrix); the orkeon CLI and the orkeon-runners container image with 104 bundled examples and local-model workflows; FSM and Graph orchestration; the Autonomous process with execution budgets; the TypeScript scripting DSL; RaggableTree semantic code analysis (15 agent tools); the plugin system; checkpoint/resume; dual-era MCP client and server; A2A task persistence; a mechanically frozen public API surface; and the LLM provider fleet grown to 16 — fourteen vendors, each under real-execution campaign proof (latest arrivals: Google Gemini, Grok/x.AI, MiniMax), plus the two aggregators OpenRouter and Mammouth AI, integrated documentation-first and awaiting their first campaign.

Every pull request is gated in CI:

• the build compiles with -warnaserror and the full .NET analyzer set — any new compiler, analyzer, or NuGet-audit warning fails the build
• the public API surface is frozen (Microsoft.CodeAnalysis.PublicApiAnalyzers; undeclared API changes are build errors)
• the unit and fast test suites (Integration/Slow suites run nightly in a dedicated workflow) and the EN/FR documentation parity gate; path-filtered gates add the examples linters on PRs touching examples/, and a strict docfx build (--warningsAsErrors) on PRs touching sources or docs

Line coverage is measured in public. The Coverage workflow runs the unit and fast suites under dotnet-coverage on every push to main (and weekly): the figure is on each run's summary page, the Cobertura file and an HTML report are its coverage artefact. No number is quoted here — a number typed into a README is a claim, a run is a measurement. Static analysis runs on a local SonarQube via scripts/sonar-analyze.sh under the quality-gate policy; its reports are not tracked by the repository, so its figures are not quoted here either.

Known constraints are tracked in docs/reference/limitations.md. What happens if the project stops — MIT, a reproducible build, no private infrastructure, forkable by anyone — is written down in SUPPORT.md.

---

Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request. Make sure the tests CI runs pass (dotnet test Orkeon.sln --filter "Category!=Integration&Category!=Slow" — CONTRIBUTING.md explains why the filter is not optional) and that new code follows the Clean Architecture conventions described in CONTRIBUTING.md.

Building from source

The scripting layer (.ork.ts support) ships a small esbuild toolchain that is bootstrapped on the first dotnet build. On a fresh clone the Orkeon.Scripting project runs npm ci (strictly from the committed tools/scripting-esbuild/package-lock.json, so the lockfile is never mutated) under tools/scripting-esbuild/ to provision node_modules/. This is a one-time, network-touching step per clone.

To skip it entirely (e.g. in CI or when packaging NuGet consumers that do not need esbuild), pass the opt-out flag:

dotnet build Orkeon.sln -p:SkipScriptingNpmInstall=true

If npm is unavailable the build still succeeds; esbuild is then resolved from PATH at runtime.

---

Community and support

• Getting help — SUPPORT.md names the venues: GitHub Discussions for questions and show-and-tell, the issue forms for bugs and feature requests. There is no Discord or Slack channel.
• Reporting a vulnerability — SECURITY.md. Never a public issue: use GitHub Private Vulnerability Reporting (repository → Security → Report a vulnerability).
• Community expectations — the Code of Conduct (Contributor Covenant 2.1) applies to every space of the project.

---

License

Orkeon is released under the MIT License.