Repository navigation
Architecture
Canonical map of how MCOS is structured. When in doubt, the source files referenced here are ground truth — every assertion on this page points to a real header, route, or test.
The architecture target is the gateway-first MCP host declared in ADR-002. The substrate question was settled by ADR-003: the legacy external gateway was retired at v0.9.0; the sole current gateway substrate is the in-process NativeHttpSysGatewayAdapter on top of HTTP.sys. The original ADR-001 LAN client identity model survives as the maintainer surface that coexists with the AI-client gateway surface. vA3.11.0 is the current alpha version; see Versions for version policy and history.
Three maintainer-deck features are part of the WinUI Shell Overview surface: direct AI plugin slots (v0.10.12+) let the maintainer activate exactly one of Claude Code, ChatGPT, or Grok as the connected client — the selections are mutually exclusive and MCOS issues the appropriate connector config on activation; the Supervisor Wizard (v0.9.76+) lets the maintainer pick a supervisor model (Claude/ChatGPT/Grok) and export a model-specific JSON config for LAN import; and the reachability self-check (v0.10.13) exposes GET /api/supervisor/reachability-check, which probes MCOS's own loopback and LAN-IP variants and reports results to the shell.
MCOS is a single Windows service hosting two logically distinct surfaces.
flowchart LR
classDef accent fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef sub fill:#0a1018,stroke:#5A00E8,color:#8CB7C4;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
subgraph AIClients[AI clients on the LAN]
AC1[Claude Code, Codex,<br/>Grok, ChatGPT, generic MCP]
end
subgraph Maintainer[Maintainer]
OP1[Browser dashboard<br/>+ WinUI shell]
end
subgraph Host[Master Control Orchestration Server <br/>single Windows service]
AIClientSurface[AI-client surface<br/>auth=none, trust=lan]:::accent
MaintainerSurface[Maintainer surface<br/>LAN-trusted with privilege gates]:::accent
end
AIClients -->|"MCP Gateway URL<br/>(advertised via DNS-SD)"| AIClientSurface
Maintainer -->|"Admin API + dashboard<br/>(per-client privilege gates)"| MaintainerSurface
AIClientSurface -.-> AIClientSurface_Note[/no app-layer auth /<br/>trust at network layer/]:::sub
MaintainerSurface -.-> MaintainerSurface_Note[/X-MCOS-Client-Id middleware /<br/>nine-flag privilege model/]:::sub
The AI-client surface is gateway-first (PHASE-02 onward). The maintainer surface preserves the ADR-001 LAN client identity model with X-MCOS-Client-Id and per-client privileges. Network firewall scoping (Profile=Private,Domain) is the load-bearing trust control on both surfaces.
flowchart TB
classDef accent fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef sub fill:#0a1018,stroke:#5A00E8,color:#8CB7C4;
classDef client fill:#031827,stroke:#5AE8FF,color:#A8DCFF;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
subgraph LANClients[LAN AI clients on remote hosts]
ClaudeCode[/Claude Code on host A/]:::client
Codex[/Codex on host B/]:::client
Other[/Generic MCP on host C/]:::client
end
subgraph Surfaces[Maintainer surfaces on the host]
Browser[Browser dashboard<br/>resources/web/]:::accent
Shell[WinUI 3 shell<br/>src/MasterControlShell/]:::accent
end
subgraph Host[Host process]
Service[[MasterControlServiceHost.exe<br/>Windows service entry point]]:::accent
Runtime[(MasterControlRuntime<br/>shared in-process core)]:::accent
end
subgraph Services[Runtime services]
direction TB
Disc[DiscoveryService<br/>Win32 DnsServiceRegister]:::accent
Beacon[BeaconService<br/>UDP discovery doc broadcast]:::accent
Onboard[OnboardingProfileService]:::accent
Gov[GovernanceBundleService]:::accent
Sup[WorkerSupervisor<br/>Job Object + stdio bridge]:::accent
Lease[LeaseRouter<br/>sticky / least-loaded]:::accent
Tel[TelemetryAggregator]:::accent
Adapter[(IMcpGateway:<br/>NativeHttpSysGatewayAdapter)]:::good
Pools[(Managed Endpoint Pools)]:::good
end
subgraph External[Spawned processes under Job Object containment]
Workers[(MCP server / sub-agent<br/>backend instances)]:::sub
end
LANClients -->|"MCP requests (HTTP /mcp)"| Adapter
LANClients -.->|"DNS-SD discovery"| Disc
LANClients -.->|"GET /.well-known/mcos.json"| Disc
LANClients -.->|"GET /api/onboarding/{type}"| Onboard
LANClients -.->|"GET /api/governance/bundles/{platform}"| Gov
Browser --> Service
Shell --> Service
Service --> Runtime
Runtime --> Disc
Runtime --> Beacon
Runtime --> Onboard
Runtime --> Gov
Runtime --> Sup
Runtime --> Lease
Runtime --> Tel
Runtime --> Adapter
Adapter ==>|"tools/call via stdio bridge"| Sup
Sup ==>|"spawns + supervises<br/>+ redirects stdin/stdout"| Workers
Adapter -->|"registers logical pools"| Lease
Lease -->|"route requests to"| Pools
Sup -->|"manages"| Pools
Pools -.->|"heartbeats"| Tel
ADR-002 §1 fixes the vocabulary. Use these terms exactly throughout the codebase, the docs, and maintainer communication:
| Term | Meaning | Lives in |
|---|---|---|
| MCP Gateway | The single MCOS-advertised MCP endpoint AI clients connect to |
IMcpGateway / NativeHttpSysGatewayAdapter
|
| LAN Discovery Service | DNS-SD + UDP beacon advertising the gateway URL | DiscoveryService |
| Client Onboarding Profile | Per-client-type config bundle MCOS hands out at first connect |
IOnboardingProfileService + /api/onboarding/{clientType}
|
| Governance Bundle | Forsetti + agentic-coding instructions per platform |
IGovernanceBundleService + /api/governance/bundles/{platform}
|
| Managed Endpoint Pool | A group of MCP-server or sub-agent instances under one supervisor | ManagedEndpointPool |
| Endpoint Instance | A single supervised backend in a pool | EndpointInstance |
| Endpoint Lease | One client-to-instance binding | EndpointLease |
| Worker Supervisor | Spawns and reaps pool instances under Windows Job Objects; redirects child stdin/stdout for the v0.6.10 stdio bridge |
WorkerSupervisor (IWorkerSupervisor::sendStdioJsonRpc) |
| Lease Router | Selects an instance per request (sticky or least-loaded) | LeaseRouter |
| Telemetry Aggregator | Events ring + client roster + gateway traffic snapshot | TelemetryAggregator |
| (IMcpGateway adapter) | The replaceable C++ interface that abstracts the gateway substrate | IMcpGateway |
If a doc or code path uses a different term for any of these, that is a drift to flag.
flowchart TB
classDef A fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef B fill:#0a1018,stroke:#5A00E8,color:#A8DCFF,stroke-width:2px;
classDef C fill:#031a14,stroke:#1cf2c1,color:#a8efe0,stroke-width:2px;
classDef D fill:#1a0f00,stroke:#FFA500,color:#FFE6BF,stroke-width:2px;
subgraph L1[Layer 1 - Surfaces]
direction LR
DashboardL1[Browser dashboard<br/>11 destinations]:::A
ShellL1[WinUI shell<br/>+ Settings panel]:::A
AdminAPI[Admin API<br/>JSON over HTTP]:::A
AIClientAPI[AI-client gateway HTTP<br/>+ DNS-SD]:::A
end
subgraph L2[Layer 2 - Coordination services]
direction LR
DiscSvc[Discovery]:::B
OnboardSvc[Onboarding profiles]:::B
GovSvc[Governance bundles]:::B
LeaseSvc[Lease router]:::B
TelSvc[Telemetry aggregator]:::B
end
subgraph L3[Layer 3 - Supervision and substrate]
direction LR
Supervisor[Worker Supervisor]:::C
GatewayAdapter[IMcpGateway adapter<br/>NativeHttpSysGatewayAdapter in-process]:::C
JobObj[Windows Job Objects]:::D
end
subgraph L4[Layer 4 - Spawned processes]
direction LR
Backends[Backend MCP servers and sub-agents<br/>spawned by supervisor with stdin/stdout pipes]:::D
end
L1 --> L2
L2 --> L3
L3 --> L4
sequenceDiagram
autonumber
participant Client as AI client
participant DNS as DNS-SD on the LAN
participant Disc as DiscoveryService
participant Onboard as OnboardingProfileService
participant Gateway as IMcpGateway
participant Pool as Managed pool
participant Lease as LeaseRouter
Client->>DNS: Browse _mcos._tcp.local
DNS-->>Client: PTR -> mcos-<instance>
Client->>Disc: GET /.well-known/mcos.json
Disc-->>Client: DiscoveryDocument (gateway URL, governance URL,<br/>onboarding paths, auth=none, trust=lan)
Client->>Onboard: GET /api/onboarding/{clientType}
Onboard-->>Client: OnboardingProfile<br/>(config snippet + manual instructions)
note over Client: Apply config snippet
Client->>Gateway: MCP request (POST /mcp)
Gateway->>Lease: acquireLease(poolId, sessionId, stateful)
Lease->>Lease: 1 sticky lookup<br/>2 least-loaded ready<br/>3 scale-out if at saturation<br/>4 fail honestly
Lease->>Pool: bind lease to instance N
Lease-->>Gateway: EndpointLease(active)
Gateway->>Pool: forward MCP request to instance N
Pool-->>Gateway: response
Gateway-->>Client: response
The lease router's four-step selection rule is locked in PHASE-07 and FORBIDDEN-CONTRACT §2.4. Hot-migration of stateful streams is forbidden — once a session has a lease, it sticks.
The seven states from PHASE-06.
stateDiagram-v2
[*] --> Configured: pool registered
Configured --> Starting: scale-up trigger or maintainer action
Starting --> Ready: probe says healthy
Starting --> Failed: spawn / probe failure
Ready --> Busy: lease acquired
Busy --> Ready: lease released
Ready --> Draining: drainPool()
Busy --> Draining: drainPool()
Draining --> Stopped: lease count = 0
Failed --> Stopped: terminal
Ready --> Stopped: shutdownAll()
Busy --> Stopped: shutdownAll()
Stopped --> [*]
Implementation: EndpointInstanceState enum in include/MasterControl/MasterControlModels.h. Test pinning: testEndpointInstanceStateAllSevenLifecycleStates in tests/MasterControlOrchestrationServerTests.cpp.
ADR-002 §9 forbids fabricated telemetry. Every numeric metric in ClientHeartbeat and WorkerTelemetry defaults to -1.0 ("unavailable"); 0.0 is reserved for genuine "idle" readings (PDH-direct host metrics only).
flowchart LR
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
classDef bad fill:#1a0a0a,stroke:#ff7a90,color:#ffd2d8;
classDef neutral fill:#0a1018,stroke:#5A00E8,color:#A8DCFF;
subgraph Source[Source of metric]
ClientReports[Client heartbeat]:::neutral
WorkerProbe[Worker probe]:::neutral
PDH[PDH host counters]:::neutral
end
subgraph Default[Default value if unreported]
Sentinel[-1.0 unavailable]:::good
IdleZero[0.0 genuine idle]:::good
Fabricated[Fake number]:::bad
end
ClientReports -->|"missing field?"| Sentinel
WorkerProbe -->|"probe never ran?"| Sentinel
PDH -->|"directly measured"| IdleZero
Fabricated -.->|"forbidden"| X[FORBIDDEN-CONTRACT 4.1 / 4.2 / 4.3 / 8.1]:::bad
The dashboard's formatMetric() helper (in resources/web/app.js) renders -1.0 as the literal string unavailable, never as 0%. The same rule applies to the WinUI shell. FORBIDDEN-CONTRACT §8.1 enforces.
ADR-002 was delivered in explicitly labeled phases (PHASE-00 through PHASE-12 and PHASE-14 complete; PHASE-13 scheduled). Every phase has its own file in handoff/realignment/ plus a completion report.
gantt
title MCOS Realignment Program (PHASE-00..PHASE-14)
dateFormat YYYY-MM-DD
axisFormat %m-%d
section Foundation
PHASE-00 Repo baseline + ADR-002 :done, p0, 2026-04-30, 1d
PHASE-01 Provider-era removal :done, p1, after p0, 1d
section Gateway plus discovery
PHASE-02 MCP Gateway spike (IMcpGateway adapter) :done, p2, after p1, 1d
PHASE-03 Bonjour LAN discovery :done, p3, after p2, 1d
section Onboarding plus governance
PHASE-04 Onboarding profiles :done, p4, after p3, 1d
PHASE-05 CLU/Forsetti governance bundles :done, p5, after p4, 1d
section Worker fabric
PHASE-06 Managed worker pools :done, p6, after p5, 1d
PHASE-07 Autoscaling + lease routing :done, p7, after p6, 1d
PHASE-08 Real-time telemetry :done, p8, after p7, 1d
section UI and release
PHASE-09 Tron dashboard realignment :done, p9, after p8, 1d
PHASE-10 Windows hardening, CI, MSI :done, p10, after p9, 1d
PHASE-11 Native gateway evaluation :done, p11, after p10, 1d
section Native gateway and shell
PHASE-12 the in-process HTTP.sys adapter :done, p12, after p11, 1d
PHASE-13 Win2D shell rendering :scheduled, p13, after p12, 1d
PHASE-14 Comprehensive diagnostics :done, p14, after p13, 1d
Each phase ended with a written completion report. PHASE-12 (native HTTP.sys substrate, v0.9.0) and PHASE-14 (comprehensive diagnostics, delivered across the v0.11.0 alpha line as Slices A–E) are complete. PHASE-13 (Win2D shell rendering) is scheduled. See Versions for the full timeline + commit SHAs.
| Directory | Purpose |
|---|---|
include/MasterControl/ |
Public C++ headers — interfaces and models |
src/MasterControlApp/ |
Runtime core: MasterControlRuntime, McpGatewayAdapters, MasterControlModels, MasterControlDefaults
|
src/MasterControlBootstrapper/ |
Setup / install / preflight logic invoked by the MSI |
src/MasterControlServiceHost/ |
Windows service host (--console mode for dev) |
src/MasterControlShell/ |
WinUI 3 desktop shell |
src/MasterControlModules/ |
Forsetti module registrations |
resources/web/ |
Browser dashboard (HTML + vanilla JS + CSS) |
resources/clu/ |
CLU governance profile JSON |
resources/icons/ |
App icon set + MSI banner / dialog bitmaps |
installer/ |
WiX v5 source for the MSI |
scripts/ |
Build, package, sync, compliance, deployment scripts |
Forsetti-Framework-Windows-main/ |
Vendored Forsetti framework — sealed by ADR-002 §11 |
tests/ |
C++ tests (MasterControlOrchestrationServerTests.cpp) |
docs/wiki/ |
Maintainer-facing documentation (mirror of the GitHub wiki) |
docs/implementation/ |
Internal architecture, schemas, drift inventory, FORBIDDEN-CONTRACT |
handoff/realignment/ |
Phase manifests + phase files + completion reports |
flowchart LR
classDef step fill:#031018,stroke:#00F6FF,color:#E6FCFF;
classDef gate fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
A[VERSION.json bump]:::step
A --> B[Sync README badges + vcpkg.json]:::step
B --> C[cmake --preset release]:::step
C --> D[cmake --build build/release --config Release]:::step
D --> E[ctest --test-dir build/release]:::gate
E --> F[Forsetti compliance script]:::gate
F --> G[mcos-contracts grep audit]:::gate
G --> H[Package-MasterControlOrchestrationServer.ps1]:::step
H --> I[Build-Msi.ps1 via WiX v5]:::step
I --> J[MSI artifact + bootstrapper preflight]:::gate
The same pipeline runs in CI via .github/workflows/windows-build-test-package.yml on every push and PR. No GitHub releases are cut while MCOS is in alpha — the CI gate is the per-commit health check; see Release Gate.
The current configuration file lives at %ProgramData%\MasterControlOrchestrationServer\config\master-control-orchestration-server.json after install. The runtime still reads %ProgramData%\MasterControlOrchestrationServer\config\master-control-program.json as a legacy fallback, and it migrates the older %ProgramData%\MasterControlProgram data directory once when the new directory is absent.
Fresh defaults are local-only. Maintainers can edit settings through the WinUI Settings panel or through GET, POST, and partial PATCH requests on /api/config. Unsafe network posture changes require X-Confirm-Unsafe: true. Key fields:
{
"instanceId": "mcos-<uuid>",
"instanceName": "Master Control Orchestration Server",
"bindAddress": "127.0.0.1",
"browserPort": 7300,
"beaconPort": 7301,
"beaconEnabled": false,
"mcpGateway": {
"type": "Native",
"enabled": false,
"listenHost": "127.0.0.1",
"listenPort": 8080,
"mcpPath": "/mcp",
"healthPath": "/health",
"mode": "local-only",
"tlsEnabled": false,
"tlsListenPort": 8443
},
"security": {
"enableTls": false,
"enableAuthentication": false,
"allowTroubleshootingBypass": false,
"allowOpenLanAccess": false
},
"resourceAllocation": {
"cpuAllocationPercent": 50,
"memoryAllocationPercent": 50,
"bandwidthAllocationPercent": 100,
"storageAllocationPercent": 50
}
}Default values come from buildDefaultConfiguration() in src/MasterControlApp/MasterControlDefaults.cpp. See Configuration for the field-by-field schema, merge semantics, and LAN enablement guardrails.
- Decisions → Architecture Decisions
- Gateway substrate → Gateway
- Pools and leases → Worker Pools
- Discovery wire format → LAN Discovery
- Telemetry surface → Telemetry and Activity
- HTTP routes → API Reference
- Dashboard tour → Dashboard
- Maintainer surface (ADR-001) → LAN Clients, Privileges, Client Config Bundle
Source for this wiki is maintained under docs/wiki/ in the Master-Control-Orchestration-Server repository.
Setup
Connect Clients
Operate
- Daily Operations
- Dashboard
- Telemetry and Activity
- Gateway
- Worker Pools
- Sub-Agents
- Governance
- CLU Governance
- Privileges
Maintain
Troubleshoot
Reference