Roll out managed MCP clients

A managed rollout makes the organization responsible for the Runtime Profile, supported client targets and unmanaged-entry policy. Do not begin with fleet enforcement. Prove the profile and recovery path on one representative host.

Rollout stages

Prepare the organization profile

Before touching client files:

1. select the organization context,
2. choose the Runtime Profile for the rollout,
3. import useful existing entries from supported clients,
4. resolve missing runtime inputs and secret references,
5. record which client targets and config paths are in scope, and
6. decide whether unmanaged entries must eventually be allowed or blocked.

Use --dry-run before every first import or sync shape.

Prepare and pilot Codex

lightnow context --tenant acme
lightnow import-config --client codex --profile platform --dry-run
lightnow import-config --client codex --profile platform
lightnow sync --client codex --profile platform --local-proxy --dry-run
lightnow sync --client codex --profile platform --local-proxy
lightnow config-status --client codex --json
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json

The CLI keeps a .lightnow.bak backup next to an existing client config before writing it. Confirm that the pilot client starts, discovers the expected tools and can complete a representative request before changing organization policy.

Configure organization policy

In LightNow Config, set the Local Proxy policy for the organization:

Setting	Rollout meaning
Enabled	Allows policy-driven Local Proxy for selected clients
Runtime Profile	Profile selected by --from-settings
Managed clients	Supported targets to which Proxy policy applies
Unmanaged entries	Allows coexistence or removes bypassing MCP entries
Policy mode	Observe records posture; enforce applies the configured boundary
Metadata-only telemetry	Enables runtime and health events without MCP payload storage

Begin with unmanaged entries allowed unless the organization already reviewed and imported every required direct entry. Blocking them is a destructive policy decision for the client file, even though a backup is created.

Apply policy to a pilot group

1

Start with one client type

Choose a representative supported target and operating system.

2

Apply settings explicitly

Run lightnow sync --client <client> --from-settings on each pilot host.

3

Verify posture and health

Check both the client file and active upstream health after restarting the client.

4

Expand by measured cohorts

Add client types and hosts only after the previous cohort has no unresolved config, authentication or upstream failures.

lightnow context --tenant acme
lightnow sync --client codex --from-settings
lightnow config-status --client codex --json

Repeat the policy sync for every managed client target. Saving organization settings alone does not rewrite files on a workstation.

Verify the managed state

For each host, record:

• client target and config path,
• selected organization and profile,
• config-status posture,
• LightNow Proxy health result,
• whether unmanaged entries remain by policy, and
• client restart and representative tool result.

managed is the desired posture when bypassing entries are blocked. mixed is valid only when organization policy intentionally allows unmanaged entries.

Recover a failed host

Do not hide a broken rollout by switching the user to an unrelated profile or anonymous mode.

1. Stop expanding the cohort.
2. Capture config-status --json and Proxy health output.
3. Fix authentication, profile readiness or the failing upstream.
4. If the written client file itself is unusable, restore its adjacent .lightnow.bak backup.
5. Re-run --from-settings only after the cause is understood.

DecisionChoose a client workflow

Confirm when policy-driven sync is the correct path.

Failure isolationDebug LightNow Proxy

Separate local config, profile resolution and upstream failures.

Rollout evidenceInspect runtime events

Use metadata-only events to observe the pilot without storing payloads.