Repository navigation
Windows Firewall LAN Mode
PHASE-10 baseline (ADR-002 §1, §10).
MCOS exposes two logically distinct surfaces. Both run on the host but are scoped differently:
| Surface | Audience | Auth | Trust | Where |
|---|---|---|---|---|
| AI-client MCP Gateway | AI clients on the trusted LAN (Claude Code, Codex, Grok, ChatGPT, generic MCP) | auth=none |
trust=lan |
Gateway port (default 8080, configurable through mcpGateway.listenPort) at /mcp
|
| Operator surface | The host operator(s) | LAN-trusted (no app-layer auth per ADR-001 §3) | trust=lan |
Admin port — the dashboard at /, JSON API at /api/*
|
The trust boundary is enforced at the network layer, not the application layer. Windows Firewall is the load-bearing control. Both surfaces refuse to participate when reachable from a Public network profile.
These are the values buildDefaultConfiguration() writes on first run. Adjust the firewall snippets below if the configuration has been edited:
| Surface | Default port | Configuration field |
|---|---|---|
| Operator dashboard / admin API | TCP 7300 | browserPort |
| Discovery beacon (UDP JSON broadcast) | UDP 7301 | beaconPort |
| MCP Gateway (AI-client surface) | TCP 8080 | mcpGateway.listenPort |
| DNS-SD / mDNS | UDP 5353 (Win32 fixed) | n/a |
Most operators want all four rules with one paste. The block below works from any non-elevated PowerShell — it triggers a UAC prompt, applies the rules from the elevated child shell, and exits cleanly. The dashboard's Settings → LAN Advertising and Windows Firewall card emits the same snippets templated to the live ports of the running instance.
$prog = 'C:\Program Files\Master Control Orchestration Server\MasterControlServiceHost.exe'
$rules = @(
@{ Name = 'MCOS - Operator Surface (LAN)'; Protocol = 'TCP'; Port = 7300 },
@{ Name = 'MCOS - MCP Gateway (LAN)'; Protocol = 'TCP'; Port = 8080 },
@{ Name = 'MCOS - Discovery Beacon (LAN)'; Protocol = 'UDP'; Port = 7301 },
@{ Name = 'MCOS - DNS-SD / mDNS (LAN)'; Protocol = 'UDP'; Port = 5353 }
)
$inner = $rules | ForEach-Object { @"
New-NetFirewallRule -DisplayName '$($_.Name)' -Direction Inbound -Action Allow ``
-Protocol $($_.Protocol) -LocalPort $($_.Port) -Profile Private,Domain ``
-Program '$prog' | Out-Null
Write-Host 'Created: $($_.Name) ($($_.Protocol) $($_.Port))'
"@ }
$tmp = [IO.Path]::ChangeExtension([IO.Path]::GetTempFileName(), '.ps1')
$inner -join "`n" | Set-Content -LiteralPath $tmp -Encoding UTF8
Start-Process powershell -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File',$tmp -Verb RunAs -Wait
Remove-Item -LiteralPath $tmp -Force
Get-NetFirewallRule -DisplayName 'MCOS *' | Format-Table DisplayName, Enabled, Direction, Action -AutoSizeIf you'd rather paste rules one at a time from an already-elevated PowerShell, the four explicit snippets are below.
After installation, add the following inbound rules. The New-NetFirewallRule snippets below are run as administrator.
New-NetFirewallRule `
-DisplayName "MCOS — MCP Gateway (LAN)" `
-Direction Inbound `
-Action Allow `
-Protocol TCP `
-LocalPort 8080 `
-Profile Private,Domain `
-Program "C:\Program Files\Master Control Orchestration Server\MasterControlServiceHost.exe"Adjust LocalPort to match mcpGateway.listenPort. The Profile Private,Domain value is the binding constraint: do not include Public. If your LAN is on the Public profile (rare, but possible on misconfigured hosts), change the profile classification on the connection rather than weakening this rule.
New-NetFirewallRule `
-DisplayName "MCOS — Operator Surface (LAN)" `
-Direction Inbound `
-Action Allow `
-Protocol TCP `
-LocalPort 7300 `
-Profile Private,Domain `
-Program "C:\Program Files\Master Control Orchestration Server\MasterControlServiceHost.exe"Adjust LocalPort to match browserPort (default 7300). Same Profile constraint.
New-NetFirewallRule `
-DisplayName "MCOS — DNS-SD/mDNS (LAN)" `
-Direction Inbound `
-Action Allow `
-Protocol UDP `
-LocalPort 5353 `
-Profile Private,Domain `
-Program "C:\Program Files\Master Control Orchestration Server\MasterControlServiceHost.exe"The Win32 DNS-SD APIs (DnsServiceRegister, DnsServiceBrowse) bind to UDP 5353. Without this rule, MCOS advertises but no client receives. Some Bonjour/mDNS responder installations create their own rule; if so, this rule is redundant.
New-NetFirewallRule `
-DisplayName "MCOS — Discovery Beacon (LAN)" `
-Direction Inbound `
-Action Allow `
-Protocol UDP `
-LocalPort 7301 `
-Profile Private,Domain `
-Program "C:\Program Files\Master Control Orchestration Server\MasterControlServiceHost.exe"The beacon broadcasts on the configurable beaconPort (default 7301). Newer clients use DNS-SD; this rule keeps the legacy UDP-JSON browser tooling working.
If MCOS is reachable on a Public profile, treat that as a misconfiguration and either:
- Reclassify the connection (Settings → Network → set the network to Private), or
- Bind MCOS to a specific LAN-only NIC via the
bindAddressfield.
The Forsetti compliance script does not enforce this; it is host-administration policy.
After adding the rules, validate from another machine on the LAN:
# From another host on the LAN — replace <host-ip> with the MCOS host's IP.
Test-NetConnection -ComputerName <host-ip> -Port 7300 # operator surface
Test-NetConnection -ComputerName <host-ip> -Port 8080 # MCP Gateway (open only when enabled and listening)
# DNS-SD validation requires Bonjour Browser or `dns-sd -B _mcos._tcp` (macOS),
# `avahi-browse _mcos._tcp` (Linux), or PowerShell:
Resolve-DnsName -Name _mcos._tcp.local -Type PTR -LlmnrFallbackThe MCP Gateway port (TCP 8080) only has a listener when the native gateway is enabled and started. The firewall rule is correct to create before enabling the gateway; Test-NetConnection reports False until the listener exists. The operator port (TCP 7300) listens unconditionally.
From a Public network, the same calls should fail. If they succeed, the Public profile is too permissive.
Uninstalling MCOS does NOT remove the firewall rules (the MSI does not own that policy state). To clean up:
Get-NetFirewallRule -DisplayName "MCOS *" | Remove-NetFirewallRule- ADR-002 — Gateway-first MCP realignment — section 1 (trust model), section 3 (LAN discovery), section 10 (release gate)
- Packaging and Gateway Binary — what the MSI installs
- Release Gate — CI / release flow
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