Repository navigation
Quick Start
This page gets MCOS built or installed on one Windows host, verifies the local admin surface, and checks LAN discovery. MCOS is internal alpha software; run the verification commands on every target host.
| Requirement | Why |
|---|---|
| Windows 11 or Windows Server 2022 | MCOS is a Windows-native C++20 application. |
| Visual Studio C++ toolchain, CMake, vcpkg | Required for source builds. |
| WiX v5 global tool | Required for MSI packaging. |
| Administrative privileges | Required for MSI install, Windows service, firewall, and certificate binding. |
| Trusted LAN peer | Required to verify DNS-SD and client reachability. |
cmake --preset release
cmake --build build\release --config Release
ctest --test-dir build\release -C Release --output-on-failure --timeout 300
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\Package-MasterControlOrchestrationServer.ps1 -Preset release -SkipBuildThe package script reads VERSION.json. For the current alpha, the MSI path is:
dist\packages\release\MasterControlOrchestrationServer-vA3.11.0-win-x64\MasterControlOrchestrationServer-vA3.11.0-win-x64.msi
If WiX is unavailable, -AllowZipOnly can produce a zip bundle, but the MSI is
the normal operator-facing installer.
Interactive install with logging:
msiexec /i "dist\packages\release\MasterControlOrchestrationServer-vA3.11.0-win-x64\MasterControlOrchestrationServer-vA3.11.0-win-x64.msi" /l*v "$env:TEMP\mcos-install.log"Silent install:
msiexec /i "dist\packages\release\MasterControlOrchestrationServer-vA3.11.0-win-x64\MasterControlOrchestrationServer-vA3.11.0-win-x64.msi" /qn /l*v "$env:TEMP\mcos-install.log"MSI option properties from installer/MasterControlOrchestrationServer.wxs:
| Property | Default | Meaning |
|---|---|---|
INSTALL_SERVICE |
1 |
Register and start MasterControlProgram. |
INSTALL_FIREWALL |
1 |
Configure Windows Firewall rules for LAN admin UI through the bootstrapper. |
INSTALL_START_MENU_SHORTCUT |
1 |
Create Start Menu shortcut. |
INSTALL_DESKTOP_SHORTCUT |
1 |
Create Desktop shortcut. |
LAUNCH_ON_EXIT |
1 |
Launch the Windows app after installation. |
The MSI does not provide a plugin-registration checkbox. Use the dashboard
toggle or scripts\Register-McosControlPlugin.ps1 after install.
Get-Service MasterControlProgram
& "C:\Program Files\Master Control Orchestration Server\MasterControlBootstrapper.exe" preflight --json-output
Invoke-RestMethod http://localhost:7300/api/health | ConvertTo-Json
Invoke-RestMethod http://localhost:7300/api/discovery | ConvertTo-Json -Depth 6
Invoke-RestMethod http://localhost:7300/api/gateway/status | ConvertTo-Json -Depth 4Default current configuration path:
%ProgramData%\MasterControlOrchestrationServer\config\master-control-orchestration-server.json
Fresh installs default to local-only. To enable the native gateway on all interfaces for a trusted LAN:
$patch = @{
mcpGateway = @{
enabled = $true
listenHost = "0.0.0.0"
mode = "trusted-lan"
}
security = @{
allowOpenLanAccess = $true
securityPosture = "trusted-lan"
}
}
Invoke-RestMethod http://localhost:7300/api/config `
-Method Patch `
-ContentType "application/json" `
-Headers @{ "X-Confirm-Unsafe" = "1" } `
-Body ($patch | ConvertTo-Json -Depth 8)
Restart-Service MasterControlProgram
Invoke-RestMethod http://localhost:7300/api/gateway/start -Method PostVerify the gateway:
Invoke-RestMethod http://localhost:8080/health | ConvertTo-Json
$init = @{
jsonrpc = "2.0"
id = 1
method = "initialize"
params = @{
protocolVersion = "2025-03-26"
capabilities = @{}
clientInfo = @{ name = "smoke"; version = "1.0" }
}
}
Invoke-RestMethod http://localhost:8080/mcp `
-Method Post `
-ContentType "application/json" `
-Body ($init | ConvertTo-Json -Depth 8)From a second host on the same LAN:
Resolve-DnsName -Name _mcos._tcp.local -Type PTR -LlmnrFallback
Invoke-RestMethod http://<mcos-host>:7300/.well-known/mcos.json | ConvertTo-Json -Depth 6macOS:
dns-sd -B _mcos._tcpLinux with Avahi:
avahi-browse _mcos._tcpIf discovery fails, check Windows Firewall and LAN Mode and Troubleshooting.
Gateway HTTPS and admin listener TLS are separate. Start with TLS and HTTPS before enabling either:
scripts\Configure-LocalServerCert.ps1 -RestartServiceThen patch mcpGateway.tlsEnabled, mcpGateway.tlsListenPort, and
mcpGateway.tlsCertThumbprint as described on the TLS page.
Fetch the onboarding profile for the client type:
Invoke-RestMethod http://localhost:7300/api/onboarding/claude-code | ConvertTo-Json -Depth 8
Invoke-RestMethod http://localhost:7300/api/onboarding/codex | ConvertTo-Json -Depth 8
Invoke-RestMethod http://localhost:7300/api/onboarding/generic-mcp | ConvertTo-Json -Depth 8Use the dashboard Onboarding page for copy/paste snippets and client-specific notes. HTTPS-capable profiles use the HTTPS gateway URL only when the runtime reports TLS as bound.
Configuration | TLS and HTTPS | Gateway | Onboarding | Windows Firewall and LAN Mode | Troubleshooting
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