π«π· Version franΓ§aise
VFS Compliance
Orkeon enforces a Virtual File System (VFS) only principle on framework code: all filesystem access must go through IFileSystemService so that mount boundaries, access rights, and path validation are respected uniformly. Direct use of System.IO.File, System.IO.Directory, FileStream, FileInfo, DirectoryInfo, and FileSystemWatcher is forbidden in framework assemblies.
This document describes:
- the
Orkeon.Compliance.VfsRoslyn analyzer that enforces the rule at build time - its seven
ORKVFSdiagnostic codes and their severities (the same analyzer also carriesORKCON001, see Console compliance) - the exempt scopes and how to opt out for documented exceptions
The analyzer
Project: src/analyzers/Orkeon.Compliance.Vfs/
Target: netstandard2.0 Roslyn analyzer, wired into src/Directory.Build.props with OutputItemType=Analyzer.
The analyzer is applied to every project under src/ except itself (a ProjectReference with ReferenceOutputAssembly=false), so violations break the build immediately. tests/analyzers/Orkeon.Compliance.Vfs.Tests exercises each rule against compiled snippets.
Calls are judged on their resolved symbol, not their spelling: using static System.IO.File; ReadAllText(p) trips ORKVFS001 like File.ReadAllText(p) does, and a target-typed FileStream fs = new(path, β¦) trips ORKVFS003 like new FileStream(path, β¦).
The same analyzer ships on NuGet as Orkeon.Compliance.Vfs (a development dependency with no Orkeon runtime dependency β see the publication matrix), for projects that want the same guard rail. Outside this repository its severities are tuned the standard Roslyn way, in .editorconfig (dotnet_diagnostic.ORKVFS007.severity = none for a project that does not use IFileSystemService).
Diagnostic codes
All diagnostics are defined in src/analyzers/Orkeon.Compliance.Vfs/DiagnosticDescriptors.cs and emit a stable help link ending in #ork-vfs-00N β the anchors in the Code column above are those targets.
Exempt scopes (path-based)
The analyzer skips file paths that match its allowlist (SystemIoUsageAnalyzer.IsExemptByPath). It is intentionally narrow β folder-wide blank checks were replaced by an explicit per-file allowlist so a new file under the same folder is not silently exempted.
Folder exemptions (s_exemptFolderSegments):
/core/Orkeon.Domain/FileSystem/β VFS public contracts (the abstraction itself)/core/Orkeon.Infrastructure/FileSystem/β VFS implementation (disk/fake/watcher)/tests/β fixtures rely onDiskBackedFileSystemServiceand real disk/examples/β out of framework compliance scope
Per-file exemptions (s_exemptFileSuffixes) β each carries inline EXCEPTION-β¦ / OUT-OF-SCOPE markers:
Sandbox/SandboxSession.csβ mounts registered before DI (EXCEPTION-BOOTSTRAP)Sandbox/HostProcessRunner.cs,Sandbox/DockerSandbox.csβ host-binary probing (OUT-OF-SCOPE)Security/PathValidator.csβ symlink/realpath resolution is its core job
Every other legitimately-raw file relies on a narrow [SuppressVfsCompliance] at the use site rather than a path exemption (see the ratified permanent exceptions below).
Opt-out: [SuppressVfsCompliance]
For documented exceptions that do not match a path-based exemption, apply the attribute declared in src/core/Orkeon.Domain/Attributes/SuppressVfsComplianceAttribute.cs (namespace Orkeon.Compliance.Vfs). The analyzer matches it by its full name, not by assembly, so a project that does not reference Orkeon.Domain declares its own internal copy β Orkeon.Hosting.Aspire does:
[Orkeon.Compliance.Vfs.SuppressVfsCompliance("EXCEPTION-BOOTSTRAP: provisions the physical directory the /sandbox mount points at")]
internal sealed partial class SandboxSession { β¦ }
[SuppressVfsCompliance("OUT-OF-SCOPE: probes external toolchain (esbuild) binary location, not a VFS mount.")]
internal string ResolveBinary() { β¦ }
Placement:
- Assembly β broad opt-out for a whole project (use sparingly, prefer a narrower scope).
- Class / struct β opt out every member of a type (e.g. a bootstrap class such as
RunnerHost). - Method / constructor / property / field β narrowest scope.
The reason argument is mandatory and should name the audit category it belongs to:
EXCEPTION-BOOTSTRAPβ runs before VFS mounts are registered.EXCEPTION-WATCHER-BRIDGEβ adapter that wrapsSystem.IO.FileSystemWatcherto implement an Orkeon watcher port.OUT-OF-SCOPEβ host-level probing (SDK install path, system binary discovery) that never targets a VFS mount.
EXCEPTION-BACKCOMPAT and EXCEPTION-OBSOLETE are not accepted categories: every tool or service
takes a non-nullable IFileSystemService (a nullable one trips ORKVFS007).
Any new class of exception should first be captured in the VFS compliance audit (the maintainers' archive, audit-vfs-compliance-*) before a suppression is added.
Ratified permanent exceptions
These accesses cannot go through the VFS by nature and are permanently allowed via the inline [SuppressVfsCompliance] markers above (or the path allowlist):
| Area | Location | Category | Why |
|---|---|---|---|
| VFS implementation | Domain/FileSystem/*, Infrastructure/FileSystem/* |
(the abstraction) | It is the VFS |
| Bootstrap (pre-DI) | SandboxSession, ConsoleApp Cli*MountBootstrapper, Hosting/Runner*, Hosting/CrewMountDeclarations (pre-reads a crew's mounts: block) |
EXCEPTION-BOOTSTRAP |
Read appsettings + mount before the VFS exists. Covers provisioning a mount, never exposing a physical path as a virtual one β see ADR-008 |
| Host probing | DockerSandbox, HostProcessRunner, ProcessGitDiffProvider |
OUT-OF-SCOPE |
Discover docker/dotnet/git on PATH, never a mount |
| Toolchain | Scripting/Toolchain/EsbuildTranspiler.cs |
OUT-OF-SCOPE |
Locates the esbuild binary + transpile temp files; host toolchain |
| Toolchain (type check) | Scripting/Toolchain/TscTypeChecker.cs |
OUT-OF-SCOPE (locating tsc), EXCEPTION-BOOTSTRAP (the scratch folder) |
tsc is an external process that reads and prints physical paths, so the checker writes a scratch folder (typings roll-up, tsconfig, copies of the script and of its imported modules with the orkeon-script pragma blanked) under the temp directory, outside the VFS and unmounted: nothing in the framework reads it back. Every path of the compiler's output and of a failure message is mapped to its virtual path before display; the folder is deleted at the end, also on cancellation |
| Host applications (pre-DI) | orkeon-host (CrewHostService, HostCrewMounts, HostStartup), Hosting/CrewDirectoryLayout, the orkeon entrypoint (Orkeon.Scripting.Cli, assembly-wide), the REPL's Program |
EXCEPTION-BOOTSTRAP |
Validate or classify operator-supplied crew, script and settings paths before any mount exists |
| Security primitive | Security/PathValidator.cs |
(allowlist) | symlink/realpath resolution is its job |
| Watcher bridge | Analysis/.../FileSystemWatcherCodebaseWatcher.cs |
EXCEPTION-WATCHER-BRIDGE |
Adapts System.IO.FileSystemWatcher to ICodebaseWatcher |
| RaggableTree probe | Analysis/Core/FileSystemDiscoverer.cs (diagnostic probe only) |
OUT-OF-SCOPE |
The batch discovery itself runs on EnumerateFilesAsync; the probe deliberately counts physical entries to distinguish "VFS yielded nothing" from "disk empty" |
| SQLite persistence | SqliteMemoryProvider, SqliteStateStore |
governed | The engine needs a real path; the Data Source is resolved via ResolveAndValidate before reaching the driver |
Adding a new tool or service
- Declare a required, non-nullable constructor parameter of type
IFileSystemServiceand inject it via DI (a nullable one tripsORKVFS007). Validate it withArgumentNullException.ThrowIfNull. - Work in virtual paths (
/workspace/...,/output/...,/tmp/...). - Never add a
string-pathSystem.IOfallback. There is no back-compat ctor β DI is the only construction path. - If you need to enumerate, stream, copy, or watch, use the dedicated
IFileSystemServicemethods rather than the equivalentSystem.IOprimitives (includingStreamReader/StreamWriterβ wrap aStreamfromOpenReadStreamAsync/OpenWriteStreamAsync, never a path).
Mounts, rights and visibility
IFileSystemService (Orkeon.Domain.FileSystem) is the whole surface a component needs:
ResolveAndValidate (virtual β physical, checked against a required FileAccessRights),
ToVirtualPath, GetAvailableMounts, EnumerateFilesAsync, ExistsAsync,
GetEntryKindAsync, TryGetEntryAsync, TryReadAllTextAsync / TryReadAllBytesAsync,
OpenReadStreamAsync, WriteAllTextAsync / WriteAllBytesAsync / AppendAllTextAsync,
OpenWriteStreamAsync / OpenAppendStreamAsync, CreateDirectoryAsync, DeleteAsync,
CopyAsync. Change notifications come from the separate IVirtualFileSystemWatcher.
AddOrkeonFileSystem(configuration) registers both.
A mount is declared as a string β [<ulid>|]<physical>:<virtual>:<rights>[;<subpath>:<rights>β¦]:
<virtual>must start with/; a physical path containing:or;, or ending with a backslash, is quoted ("C:\src\":/workspace:ro).<rights>isro(FileAccessRights.ReadOnly),rw(ReadWrite= Read, Write, Create, Delete) orrwnd(ReadWriteNoDelete); each;<subpath>:<rights>overrides the rights of a subtree.- The optional 26-character ULID before
|identifies the entry β see the configuration reference.
FileAccessRights is a flags enum (Read, Write, Create, Delete); every operation
states the right it needs and the registry refuses the call when the mount (or the subtree
override) does not grant it. MountVisibility is AgentFacing (the default, listed by
GetAvailableMounts and in the agent prompt) or Internal (below).
Working directory and relative paths
The registry holds one working directory (FileSystemRegistry.WorkingDirectory, exposed as
IFileSystemService.WorkingDirectory): the directory a host designated with
SetWorkingDirectory(virtualPath) (an absolute path inside an agent-facing mount, without . or
.. segments) while its mount is registered, else /workspace when an agent-facing mount claims
it, else none. The runners designate it from Orkeon:FileSystem:WorkingDirectory, else take
/workspace, else /output; a per-execution registry (ScopedMountComposition) keeps
the boot one while it still mounts it.
- A file tool (
file_read,file_write,edit_file,glob,grep,directory_read,directory_search,count_pattern, thenode_*tools,edit_batch, and the data toolscsv_reader,docx_reader,docx_writer,xlsx_reader,xlsx_writer,pdf_reader,xml_parser) resolves a relative path against the agent'sworking_rootwhen it has one, else against the working directory (WorkingDirectoryResolver.Absolutize):src/./lib/../stats.jsbecomes/workspace/src/stats.js, every later call addresses that path, and the response echoes it. The path is made absolute before the mount check and the root guard, so../p2/xfrom a root/workspace/wt/p1is refused as outside the root. With no working directory a relative path is refused.structural_searchandstructural_rewrite(paths),txt_searchandmdx_search(path) resolve the same way, and every tool of this list,node_outlineandnode_readincluded, refuses a path outside the agent's root before any I/O. - An empty
pathis refused withpath is required: the absolute path of the file, e.g. /workspace/src/stats.js. - A path that starts with no mount is refused with the shape of an address:
No mount found for virtual path 'x': a path starts with a mount: /workspace/src/stats.js. Available mounts: .... shell_commandwithoutworking_directoryruns in the agent's root, else in the working directory; a relativeworking_directoryresolves the same way. It never falls back to the first mount that grants the rights: with mounts but no working directory the call is refused and names the mounts. The relativeworking_directoryis made absolute before the root guard, so../p2from a root/workspace/wt/p1is refused.- A write directory (
FileSystemRegistry.WriteDirectory,IFileSystemService.WriteDirectory) takes a writingshell_commandthat names noworking_directory, runs under no agent root, and whose working directory is refused for its rights alone. A writing command (any command but the read-only allowlist) needs every right on its working directory: read, write, create and delete; a read-only/workspace, as inorkeon forge, lacks them. Any other refusal (no mount, a traversal, a path the runtime reserves, the path validator) is reported as is. It is the directory designated byOrkeon:FileSystem:WriteDirectory(SetWriteDirectory, an absolute path without.or..segments whose effective rights, subtree overrides included, grant Write in an agent-facing mount, else the host refuses to start), else/outputwhen an agent-facing mount grants Write there, else none. It never comes from the order of the mounts. Nothing changes when the working directory grants every right (a/workspacemounted read-write); under an agent root there is no fallback; with no write directory the refusal names the option. The file tools' relative paths still resolve against the working directory only. - A per-execution registry carries the boot working and write directories forward
(
WorkingDirectoryDesignation.CarryForward) while it still mounts them; theorkeon forgetrial (ForgeTrialScope.Compose) goes through it too, else it takes its own/workspaceor/output.
Agent working root vs mount
An agent may declare a working_root (YAML; AgentBuilder.WorkingRoot(string); .workingRoot(path) on a
script agent of .ork.ts): a virtual path
such as /workspace/.orkeon/worktrees/x that must lie under a mount, else the run is refused at
start with an error naming the root. It is an intersection with the mounts, never an extension:
- file tools (
FileToolBase.ResolveVirtualPath, throughAgentRootGuard) refuse, before any I/O, a path on the same mount that lies outside the root; other mounts (/output,/tmp) keep their own rights; shell_commandrefuses a working directory or a path argument outside the root, defaults its working directory to the root, and narrows its sandbox's confined paths to it (plus, when the root is a linked git worktree, the git dirs it commits through: Shell confinement);- a refusal reuses the VFS denial shape: physical paths are redacted.
A script agent's root holds every tool its body runs. ctx.llm.act and ctx.tools run as the agent.
The global tools namespace cannot tell which agent calls it, so it follows the open agents' root while
they share one and refuses the call when agents with different roots run at once: a body that runs beside
others calls ctx.tools. A child started by spawn_agent or ctx.spawnBackground without a root of its
own runs under its parent's, and so does each later crew.send to that instance.
Absent, nothing changes: the mounts alone confine the agent.
Agent file-system scope
An agent may also declare a filesystem: list (YAML; AgentBuilder.FileSystem(...) in C#;
.filesystem([...]) on a script agent of .ork.ts): the only virtual paths its tools may touch. An entry
is a path, or {path, access} with access one of ro, rw, rwnd:
agents:
writer:
filesystem:
- /workspace/docs # the mount's own rights there
- path: /output/report
access: rwnd # narrowed to read-write, no delete
- The rights come from the mount: an entry selects and narrows (an intersection), never extends. An entry
under no mount, or an
accessthe mount does not grant there (its sub-path overrides included), refuses the run at start with an error naming the agent and the entry; so do a relative path, a.., an entry declared twice and an entry whose access grants no right. An empty list is refused at load. - A declared scope is exhaustive: during the agent's tool calls, the file system refuses every path outside
it on every mount, in its usual denial shape (
Access denied for '<virtual path>'), naming the agent and its scope and no other mount. The check sits inFileSystemService.ResolveAndValidate, before the mounts', so every tool that goes through the VFS is held: the file tools,list_mounts(which lists the scope's entries with the rights in force there),glob/grep, the search, PDF and RAG tools, the e-mail and drive attachments. A path the scope grants but a mount refuses is denied in the same shape, naming the scope, never the run's other mounts.shell_commandbinds the scope's entries alone in its sandbox, each with the rights in force there. - A checked path is read as the host reads it, and when that reading is ambiguous the scope grants only
what every reading grants. Off Windows a backslash is part of a name (
/output/notes\x.mdis the filenotes\x.mdof/output), save right after a mount root, where the registry takes it as a separator. The most specific entry is also sought without case and without trailing dots or spaces in a segment, so a case-insensitive host (/output/REPORT, or/output/report.on Windows) never gets more than that entry grants. The scope may so refuse a path a case-sensitive host would allow, never the reverse. - A listing under a scope (
directory_read,glob,grep, any enumeration of the VFS) gives only the entries a read would allow, each checked against the scope and the mount's sub-path overrides. A recursive delete is refused before anything is removed when an entry below the directory withholdsDelete(/outputrw,/output/reportro). - The semantic-graph tools read an index another run may have filled: during a scoped call they leave
out every node whose file the scope does not let the agent read, and whatever names one (an edge, a
call path, a cycle, a search hit, a complexity or centrality entry, a symbol's source, cached or not). A
monorepo or package node (a directory) stays visible on the way to an entry of the scope; a node without
a virtual path (an external symbol, a node of a Firefox page outline) is kept.
rag_ingestjudges every source that is not a web address, whatever its spelling (relative, backslashed, Windows-rooted).start_jobwrites its job log underjobs/of a place the scope lets the agent write (/output/jobsfirst), else is refused with the scope named. - Only the agent's tool calls are held. The framework's own I/O during the run (memory, knowledge, output files, manifests) is not the agent's and keeps the mounts' rights.
- A child started from a scoped agent's tool call (
spawn_agent, a delegated task,ctx.spawnBackground, a latercrew.sendto that instance) runs under its parent's scope; its ownfilesystem:can only narrow it, and an entry outside the parent's scope or above its rights refuses the child's run. A child that declares none holds its parent's rights under its own agent name, which its denials and its prompt name. - In
.ork.ts,ctx.delegatehands the caller's scope down asdelegate_work_to_coworkerdoes (the delegated agent's working root stays its own). A run the script starts itself while agents run (crew.run,crew.runAgent,crew.runStream, a sub-crew's) takes the open attempts' scope, and is refused when their scopes differ;tools.*from code is held the same way. Scopes are compared by what they grant, the parent chain included. An agent'sonAgentStart/onAgentStophooks run their tools under the agent's working root and scope, a crew hook under the first agent's; a lifecycle hook whose agent scope the mounts refuse is not run, and a warning says why.rag.ingestcalled from a scoped body expands its globs under the scope and refuses a source outside it. - With a
working_root, the root must lie inside the scope (else the run is refused): the scope says what the agent may touch, the root where it works by default and where relative paths resolve. Set both to give a scoped agent a default directory.
Absent, nothing changes: the mounts (and the working_root, if any) alone confine the agent.
The file system in the prompt
An agent with a file-system tool (IBaseTool.UsesFileSystem: the file, search, RAG, attachment tools,
email_parser, image_generation, firefox, index_codebase, incremental_reindex, list_mounts,
shell_command) gets a ## File system section in its system prompt: its scope's entries, else the
run's agent-facing mounts (internal ones never), each with its rights and sub-path overrides, sorted by
virtual path so the prompt is the same from run to run; then its working root, or the directory relative
paths resolve against (said to lie outside the scope when it does, so that the agent writes every path
in full). announce_mounts: false turns it off, for one agent or, at crew level, for
every agent that does not set its own (AgentBuilder.AnnounceMounts(false), .announceMounts(false)). A
script agent's ctx.llm.act prompt is the script's own and carries no such section: the body reads it as
ctx.fileSystem.prompt (the same text, "" when no path is visible, when the agent has no file-system tool or
when it sets .announceMounts(false)) and places it where it wants (AgentFileSystemPrompt.Render renders it for
both shapes).
Internal roots and privileged access
A runner mounts a few roots for itself as internal mounts (Orkeon:FileSystem:InternalMounts,
MountVisibility.Internal): /llm-logs (the --llm-log exchange files), /sandbox (where the
code sandboxes stage what they run), /state (the checkpoint store), /runs (the run history),
/llm-mock and /llm-cassette (--llm-mock, --llm-record/--llm-replay) and /credentials (the OAuth tokens of the e-mail and drive accounts β
mounted only when an OAuth account of either family is declared). The registry refuses an internal mount to every
ordinary caller and reports it like a path that does not exist, so no agent-facing tool can reach
or even name one (ADR-008). The few
components that must write there ask DI for PrivilegedFileSystemAccess by name: the exchange
logger, the code sandboxes and the token stores (FileSystemEmailTokenStore and
FileSystemDriveTokenStore, which the runner host registers over /credentials/email and
/credentials/drive). They still go through the VFS. The only raw
System.IO on that path is the runner creating the physical credentials directory and its
email and drive subdirectories (owner-only on Unix) before any mount exists β Hosting/Runner* bootstrap,
an already-ratified EXCEPTION-BOOTSTRAP scope, not a new category. orkeon run refuses a user
mount claiming one of these roots (EnsureReservedRootsAreFree, /state and /runs included);
every other entry point refuses the roots it reserves for itself (/crew and /sandbox for
--list-tools and mcp serve), and all of them refuse /credentials, whatever the accounts.
Per-scope mounts (ambient mount override)
The mount set is a boot-time singleton: AddOrkeonFileSystem builds one FileSystemRegistry from
Orkeon:FileSystem:Mounts, and IFileSystemService is a singleton over it. That is correct for a
single-tenant runner, but a host that runs many crews in one process (e.g. a run engine driving a
different profile per run) needs to give one execution flow its own mounts without disturbing the
others.
IFileSystemService cannot become DI-scoped for this: dozens of singletons inject it, so a scoped
lifetime would be a captive dependency. Instead, per-scope mounts are provided by an ambient
override β IFileSystemScope (registered as a singleton, backed by AsyncLocal<FileSystemRegistry?>,
AsyncLocalFileSystemScope). The singleton FileSystemService reads it per operation: it resolves
against the ambient registry when an execution flow has entered one, and against the boot registry
otherwise. AsyncLocal isolates the value per asynchronous control flow, so concurrent runs never see
each other's mounts, and a host that never enters a scope keeps byte-identical behavior.
// Inside a run scope: install this run's mounts for this async flow only.
var granted = grantedMountStrings.Select(FileSystemMount.Parse).ToList();
using var registry = ScopedMountComposition.ForExecution(bootRegistry, granted);
using var _ = fileSystemScope.Enter(registry); // restored on dispose (nesting supported)
// Every IFileSystemService call on THIS async flow now resolves against `granted`;
// other concurrent runs continue to see the boot mounts.
Compose, never hand-build. Entering a scope REPLACES the mount set β ActiveRegistry is
scope?.Current ?? boot, never a union β so a registry built from one execution's own folders
alone takes the whole boot set down with it for the length of that flow. ForExecution
therefore carries the boot mounts forward and lets the execution's own shadow them at the
virtual paths they claim; substitution rather than addition is the point of the mechanism, since
two crews each granted /output over different folders is exactly what one flat registry cannot
express.
Both halves of the boot set have to survive, for different reasons. The Internal ones
(RunnerVirtualRoots: /llm-logs, /sandbox, /state, /runs, /credentials, β¦) are a confidentiality matter: dropping them stops
exchange logging, both code sandboxes and the e-mail token store resolving, and it drops
IsUnderInternalMountUnsafe, the check that stops any of them gaining a second, agent-reachable
address through one of the execution's own mounts. The agent-facing ones are just as load-bearing: orkeon-host mounts each hosted
crew's directory under /crews and then loads the crew by that virtual path, from inside the
scope. A registry composed of the execution's own mounts alone would leave the crew unreachable, and
ExistsAsync, which swallows the denial, would surface it as a generic run failure.
Who enters one today. orkeon-host is the one shipped runner host that does, once per
hosted crew, from Orkeon:Host:Crews:*:Mounts β so two hosted crews may each address their own
/output over different folders, which the single flat boot registry cannot express. The orkeon forge trial (ForgeTrialScope) enters one too, over its trial folders. Every other
runner keeps the boot mounts: one process per launch makes the question moot for them.
The guards apply to scoped mounts exactly as to boot mounts, because they run per operation over
whichever registry is active: the registry enforces mount rights + path-traversal containment, and
IPathValidator independently enforces the workspace-root / blocked-path / extension checks
(PathSecurity:DefaultWorkspaceRoot, AdditionalAllowedDirectories). A folder granted in
Orkeon:Host:Crews:*:Mounts is an entry of the daemon: it is readable wherever it lies, without
--allow-external-mounts. The caller owns
the scoped FileSystemRegistry's lifetime (Enter does not dispose it β dispose it yourself, as above).
CI behaviour
All seven diagnostics (ORKVFS001βORKVFS007) are errors, so CI blocks any merge that reintroduces System.IO file access, a string-path StreamReader/StreamWriter, a Path.GetFullPath on user input, or a nullable IFileSystemService in framework code without a justified [SuppressVfsCompliance] attribute.