Repository navigation
Remote Client
How an AI coding agent on another LAN host joins the control plane. The operator registers the client, downloads a server-authored config bundle, and hands it to the agent's host. Identity is by
clientIdonly on a trusted LAN.
flowchart LR
classDef accent fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
classDef faint fill:#0a1018,stroke:#5A00E8,color:#8CB7C4;
Beacon[(LAN beacon)]:::faint
Op((Operator)):::accent
MCOS[[MCOS<br/>:7300]]:::accent
Bundle{{config bundle}}:::accent
Host[Agent host]:::good
Agent[/AI agent/]:::good
Beacon -.discover.-> Op
Op -->|register| MCOS
Op -->|grant privileges| MCOS
MCOS --> Bundle
Op -->|hand over| Host
Host --> Agent
Agent -- "X-MCOS-Client-Id" --> MCOS
Five-minute walkthrough: discover → register → privilege → bundle → consume → operate.
sequenceDiagram
autonumber
participant Op as Operator (MCOS host)
participant MCOS
participant Disk as Operator disk
participant Host as Remote host
participant Agent as AI agent
Note over Op,MCOS: Discovery
Op->>MCOS: GET /api/beacon
MCOS-->>Op: { instanceName, host, ip, browserPort:7300 }
Note over Op,MCOS: Registration
Op->>MCOS: POST /api/clients<br/>{ clientId, displayName, clientType, hostName }
MCOS-->>Op: 200 LanClient { enabled:true, privileges:all-false, autonomousMode:false }
Note over Op,MCOS: Privileges
Op->>MCOS: POST /api/clients/{id}/privileges<br/>{ canCreateMcpServers:true, ... }
MCOS-->>Op: 200 updated
opt autonomous worker
Op->>MCOS: POST /api/clients/{id}/autonomous-mode<br/>{ autonomousMode:true }
MCOS-->>Op: 200 updated
end
Note over Op,Host: Bundle handoff
Op->>MCOS: GET /api/clients/{id}/config
MCOS-->>Op: 200 schemaVersion 1.0 JSON
Op->>Disk: save lan-client-{id}.json
Op-)Host: scp / share / paste
Note over Host,MCOS: First contact
Host->>Agent: start with bundle path
Agent->>Agent: parse JSON, cache fields
Agent->>MCOS: POST /api/client/heartbeat<br/>X-MCOS-Client-Id: {id}
MCOS-->>Agent: 200 lastSeenUtc updated
Note over Agent,MCOS: Discovery + work
Agent->>MCOS: GET /api/client/mcp-servers
MCOS-->>Agent: 200 [shared catalog]
Agent->>MCOS: POST /api/runtime/mcp-servers (privilege-gated)
MCOS-->>Agent: 200 succeeded
If the agent's host doesn't already know which machine runs MCOS, hit the LAN beacon:
curl http://<mcos-host>:7300/api/beacon | jq{
"instanceName": "MCOS-PC-GAMING-R7-58",
"host": "PC-GAMING-R7-58",
"ip": "192.168.1.10",
"browserPort": 7300,
"beaconPort": 7301,
"platforms": ["windows", "macos", "ios"]
}UDP beacons advertise the same payload on beaconPort (default 7301) at beaconBroadcastIntervalSeconds cadence (default 15s) — useful for headless agents that scan rather than configure a host.
flowchart LR
classDef accent fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
A[Agent host knows<br/>MCOS hostname?] --> B{Yes?}
B -->|yes| Skip[Skip discovery]:::good
B -->|no| UDP[Listen on UDP :7301<br/>OR run nmap LAN scan]:::accent
UDP --> Catch[Catch beacon payload]:::accent
Catch --> Hit[curl http://host:7300/api/beacon]:::accent
Hit --> Skip
The operator chooses a stable clientId (lower-case slug; the only LAN identity for the agent):
curl -X POST http://<mcos-host>:7300/api/clients \
-H "Content-Type: application/json" \
-d '{
"clientId": "claude-code-jdaley-wks",
"displayName": "Claude Code on Jdaley workstation",
"clientType": "claude_code",
"hostName": "PC-GAMING-R7-58"
}'Or via the dashboard's Register LAN Client quick action on the home hero.
<vendor>-<role>-<host>
claude-code-jdaley-wks # Claude Code on a workstation
codex-build-ci-runner # Codex on a CI runner
xai-sentinel-prod # xAI on a production sentinel
The slug is opaque to MCOS — pick something operationally readable.
Defaults are all-false (read-only client). Grant only what the agent needs.
curl -X POST http://<mcos-host>:7300/api/clients/claude-code-jdaley-wks/privileges \
-H "Content-Type: application/json" \
-d '{
"canCreateMcpServers": true,
"canCreateSubAgents": true
}'flowchart TD
classDef accent fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
R[Read-only consumer]:::good --> R1[no privileges]
T[Tool author]:::accent --> T1[canCreateMcpServers<br/>+ canModifyMcpServers]
A[Sub-agent author]:::accent --> A1[canCreateSubAgents<br/>+ canModifySubAgents]
O[Operator-equivalent]:::accent --> O1[all 9 flags]
Auto[Autonomous worker]:::accent --> Auto1[create flags<br/>+ autonomousMode true]
See Privileges for the full nine-flag table and capability bundles.
Autonomous mode lets the agent create MCP servers and sub-agents without per-action approval (CLU still records, but doesn't gate). Modify and remove still flow through the full gate.
curl -X POST http://<mcos-host>:7300/api/clients/claude-code-jdaley-wks/autonomous-mode \
-H "Content-Type: application/json" \
-d '{"autonomousMode": true}'
⚠️ RequiresaiAutonomyEnabled = truein/api/config. CLU-C009 blocks the enable otherwise.
curl http://<mcos-host>:7300/api/clients/claude-code-jdaley-wks/config \
> lan-client-claude-code-jdaley-wks.jsonOr click Download config bundle in the per-client drawer of the dashboard.
The bundle is a schemaVersion: "1.0" JSON document — see Client Config Bundle for every field.
jq '{ server: .mcosServer, header: .identification, privileges: .privileges, auto: .autonomousMode }' \
lan-client-claude-code-jdaley-wks.json{
"server": "http://192.168.1.10:7300",
"header": { "header": "X-MCOS-Client-Id", "value": "claude-code-jdaley-wks" },
"privileges": { "canCreateMcpServers": true, "canCreateSubAgents": true, ... },
"auto": false
}If mcosServer reads 0.0.0.0 you've hit a server bug — open an issue. The resolver should never emit wildcard.
Drop lan-client-<clientId>.json somewhere the agent's host process can read.
flowchart LR
classDef accent fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
Op[Operator desk]:::accent --> Choice{Transfer mechanism}
Choice --> A[scp / sftp]:::good
Choice --> B[Network share<br/>SMB / NFS]:::good
Choice --> C[Paste over RDP/SSH]:::good
Choice --> D[USB / Yubikey for air-gap LAN]:::good
A --> Drop[~/.config/mcos/<br/>lan-client-{id}.json]:::accent
B --> Drop
C --> Drop
D --> Drop
There's no signature, no token rotation, no proof-of-possession as of v0.7.0 — the bundle is the ergonomic equivalent of "here's the URL, here's the header value to send". The trust model is the LAN itself, scoped by Windows Firewall Profile=Private,Domain rules.
import json, time, requests
with open("lan-client-claude-code-jdaley-wks.json") as f:
bundle = json.load(f)
assert bundle["enabled"], "client disabled — refusing to start"
mcos_url = bundle["mcosServer"]
header_name = bundle["identification"]["header"] # always "X-MCOS-Client-Id"
header_value = bundle["identification"]["value"] # the clientId
privileges = bundle["privileges"]
autonomous = bundle["autonomousMode"]
session = requests.Session()
session.headers.update({header_name: header_value})
# Discover the shared fabric — every client sees everything:
mcp_servers = session.get(mcos_url + bundle["catalogs"]["mcpServers"]).json()
sub_agents = session.get(mcos_url + bundle["catalogs"]["subAgents"]).json()import { readFileSync } from "node:fs";
const bundle = JSON.parse(readFileSync(process.argv[2]!, "utf8"));
if (!bundle.enabled) throw new Error("client disabled");
const fetchMcos = (path: string, init?: RequestInit) =>
fetch(`${bundle.mcosServer}${path}`, {
...init,
headers: {
[bundle.identification.header]: bundle.identification.value,
...(init?.headers ?? {}),
},
});
const catalog = await (await fetchMcos(bundle.catalogs.mcpServers)).json();
console.log(`shared MCP catalog: ${catalog.mcpServers.length} entries`);$bundle = Get-Content lan-client-claude-code-jdaley-wks.json | ConvertFrom-Json
$headers = @{ ($bundle.identification.header) = $bundle.identification.value }
Invoke-RestMethod -Method Post `
-Uri "$($bundle.mcosServer)/api/client/heartbeat" `
-Headers $headersAny authenticated request implicitly updates lastSeenUtc. A busy agent never needs a separate heartbeat. An idle agent should heartbeat to stay on the live badge in the dashboard:
while running:
session.post(mcos_url + "/api/client/heartbeat")
time.sleep(30) # 30s cadence is comfortable; the 60s threshold is looseflowchart LR
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
classDef warn fill:#1a0f00,stroke:#FFA500,color:#FFE6BF;
classDef faint fill:#0a1018,stroke:#5A00E8,color:#8CB7C4;
A[lastSeenUtc] --> Now{now - lastSeen}
Now -->|< 60s| Live[live badge]:::good
Now -->|60s..5m| Stale[stale badge]:::warn
Now -->|> 5m| Quiet[quiet — no badge]:::faint
The thresholds are dashboard cosmetics; the server doesn't auto-disable on staleness. Disablement is operator-driven.
Pre-check locally to avoid burning a round trip:
def can(flag: str) -> bool:
return privileges.get(flag, False) or (autonomous and flag in CREATE_FLAGS)
CREATE_FLAGS = {"canCreateMcpServers", "canCreateSubAgents"}
if can("canCreateMcpServers"):
resp = session.post(mcos_url + "/api/runtime/mcp-servers", json={
"id": "shared-fs",
"displayName": "Shared filesystem MCP",
"kind": "stdio",
"endpoint": "fs-bridge",
"args": []
})
if resp.status_code == 403:
# Privilege revoked since bundle was issued — re-fetch and retry
refetch_bundle()The server is the source of truth. If a privilege has been revoked since the bundle was issued, the server returns HTTP 403 with the missing privilege named:
{ "succeeded": false, "errorMessage": "Required privilege missing: canCreateMcpServers" }That's the signal to re-fetch the bundle.
preview = session.post(mcos_url + bundle["governance"]["decisionEndpoint"], json={
"action": "mcp_server_remove",
"targetId": "shared-fs"
}).json()
if preview["outcome"] == "block":
log.warning(f"CLU will block: {preview['ruleId']} {preview['message']}")
elif preview["outcome"] == "requires_operator_approval":
log.info(f"CLU will defer; queue id will be {preview.get('deferredActionId')}")The Phase-6 stub returns outcome: "deferred" with HTTP 202; Phase-7+ returns real Allow / Block / RequiresOperatorApproval. Pre-check is an optimization — the actual mutation still goes through the full gate when issued.
flowchart LR
classDef accent fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef warn fill:#1a0f00,stroke:#FFA500,color:#FFE6BF;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
P[privilege flag toggled]:::warn --> R[re-fetch bundle]:::accent
A[autonomousMode toggled]:::warn --> R
Net[bind address / port changed]:::warn --> R
Disable[client disabled]:::warn --> Off[refuse to start]:::warn
Rename[displayName updated]:::good --> Skip[no re-fetch needed]:::good
Profile[CLU profile rewritten]:::good --> Live[live read via profileEndpoint]:::good
Re-fetch is operator-driven. Bundles do not expire; there is no clock-bound rotation.
A request without X-MCOS-Client-Id resolves to the operator-fallback context with full privileges. This is intentional — it lets the operator hit admin routes from the browser without an operator-login flow, and lets ad-hoc curl from the MCOS host work.
⚠️ A remote AI agent that omits the header silently inherits operator authority. Ensure your agent always sends the header. Production deployments where this matters should setbindAddressto a non-wildcard interface and rely on LAN-level network controls.
A future hardening track can add bearer tokens or mTLS without re-architecting; the bundle's identification field shape leaves room.
A request bearing X-MCOS-Client-Id for a disabled client is rejected at the middleware before any route handler runs:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{ "succeeded": false, "errorMessage": "LAN client is disabled: claude-code-jdaley-wks" }Re-enable via POST /api/clients/{id}/enable to restore. The agent should detect 403 + the disabled message and back off (don't hammer the heartbeat in a tight loop).
Symptoms:
- Agent's local
privilegesno longer match server reality - HTTP 403 with "Required privilege missing: X" on a flag the bundle says is
true - HTTP 403 with "LAN client is disabled" despite bundle showing
enabled: true
Recovery:
- Operator inspects
/api/clients/{id}to confirm current state - Re-issues bundle:
curl /api/clients/{id}/config > lan-client-{id}.json - Hands over the new bundle
- Agent reloads bundle (restart or hot-reload) and resumes
flowchart TD
classDef warn fill:#1a0f00,stroke:#FFA500,color:#FFE6BF;
classDef good fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
A[Agent: connect timeout to bundle.mcosServer]:::warn --> B{ping the IP/hostname}
B -->|fail| C[LAN routing issue<br/>or host down]:::warn
B -->|ok| D{telnet to :7300}
D -->|fail| E[Firewall blocking 7300<br/>or service not running]:::warn
D -->|ok| F[Bundle URL malformed?<br/>Check logs]:::warn
C --> Fix1[Investigate network<br/>or operator's host]:::good
E --> Fix2[Open the port,<br/>start the service]:::good
F --> Fix3[File issue<br/>resolver bug]:::good
Common pitfall: the bundle was issued on a host whose bindAddress = 0.0.0.0 and preferredBindAddress was unset. The resolver fell back to 127.0.0.1. Set preferredBindAddress to the LAN-routable IP, then re-issue.
Alpha is autonomous, Bravo only consumes:
# Operator registers both
curl -X POST http://192.168.1.10:7300/api/clients \
-H "Content-Type: application/json" \
-d '{ "clientId":"alpha", "displayName":"Alpha builder", "clientType":"claude_code" }'
curl -X POST http://192.168.1.10:7300/api/clients/alpha/autonomous-mode \
-H "Content-Type: application/json" -d '{ "autonomousMode": true }'
curl -X POST http://192.168.1.10:7300/api/clients \
-H "Content-Type: application/json" \
-d '{ "clientId":"bravo", "displayName":"Bravo consumer", "clientType":"codex" }'
# Bundles
curl http://192.168.1.10:7300/api/clients/alpha/config > alpha.json
curl http://192.168.1.10:7300/api/clients/bravo/config > bravo.json
# Drop alpha.json on host A, bravo.json on host B
# Alpha (host A) creates an MCP server:
curl -X POST http://192.168.1.10:7300/api/runtime/mcp-servers \
-H "Content-Type: application/json" \
-H "X-MCOS-Client-Id: alpha" \
-d '{ "id":"shared-fs", "displayName":"Shared FS", "kind":"stdio", "endpoint":"fs", "args":[] }'
# Bravo (host B) sees it in the shared catalog:
curl -H "X-MCOS-Client-Id: bravo" http://192.168.1.10:7300/api/client/mcp-servers \
| jq '.mcpServers[] | select(.id == "shared-fs")'Both hosts see the same shared fabric. Mutation authority diverges by privilege.
Q: Can two agents on the same host share a clientId? Technically yes, but you collapse attribution and dilute the activity stream. Register two clients (e.g.
claude-code-host-aandclaude-code-host-b) and issue separate bundles.
Q: What if the agent runs on the same host as MCOS? Works the same. Bundle's
mcosServerwill resolve to127.0.0.1if no preferred address is set. Header still required.
Q: Can the agent self-rotate
clientId? No. ID rotation is an operator action: register the new id, transition work, disable + delete the old.
Q: Does
clientTypeaffect behavior? No. It's cosmetic — used in dashboards and logs. The privilege gate and CLU don't branch on it.
Q: Do agents need to send the header on
/api/beacon? No. Beacon is anonymous discovery; no header required, no privilege resolution.
- LAN Clients — the data model and lifecycle
- Privileges — the nine flags and capability bundles
- Client Config Bundle — full bundle field reference
- Governance — CLU enforcement and the approval queue
- API Reference — every admin and client route
- ADR-001 — trusted-LAN posture rationale
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