vscode/scripts/mock-policy-server

Mock Copilot policy server

Local Node server and web GUI for the four Copilot policy endpoints used by DefaultAccountService. Mock selected endpoints while forwarding the rest to the real API. It has no runtime dependencies and is not shipped with VS Code.

Start

npm run mock-policy-server

Open http://127.0.0.1:3000. Managed settings is mocked by default. Use the switch beside each endpoint tab to choose mock or passthrough. Presets apply immediately; response behavior, status, and JSON edits auto-save.

The GUI opens on the Policies workspace. Select Setup in the header to open a modal that guides you through either connection method:

• System proxy (recommended): works with Code OSS, Stable, Insiders, Copilot CLI, and SDK/runtime clients. The page recommends Proxyman on macOS and provides a Map Remote rule. VS Code normally uses the system proxy; the http.proxy setting is available as an optional fallback when explicit client configuration is needed.
• Code OSS overrides: the quicker option for Code OSS from this checkout. Select Apply Overrides, reload, and sign in. This option does not redirect SDK/runtime requests.

After connecting, open the VS Code Command Palette and run > Developer: Sync Account Policy. To refresh the policy used by Local Agent Host, also run > Developer: Restart Local Agent Host.

The Setup dialog checks Code OSS overrides directly. It tests the system proxy by sending a request without credentials to the managed settings URL and confirming that the response came from this local server. It does not inspect Proxyman or macOS proxy configuration. The test runs automatically, and the global header always shows a green or red connection indicator.

If no real request appears in Live Requests, use Clear Policy Cache. A fresh managed-settings cache entry can prevent the client from making a request for up to one hour. Then run the commands above again.

Other Copilot clients share that cache. For an isolated run, start both the server and Code OSS with the same temporary cache home:

COPILOT_CACHE_HOME="$PWD/.build/mock-policy-cache" npm run mock-policy-server
COPILOT_CACHE_HOME="$PWD/.build/mock-policy-cache" ./scripts/code.sh

HTTP API

The control API is JSON-only and supports complete configuration without the GUI. Start with its machine-readable index and current state:

BASE=http://127.0.0.1:3000
curl "$BASE/api"
curl "$BASE/api/state"

GET /api/state returns endpoint IDs, presets, current bodies, statuses, and mock/passthrough state.

Apply a known preset:

curl -X POST "$BASE/api/state" \
  -H 'Content-Type: application/json' \
  -d '{"endpoint":"managedSettings","preset":"not-configured"}'

Set a custom response:

curl -X POST "$BASE/api/state" \
  -H 'Content-Type: application/json' \
  -d '{"endpoint":"managedSettings","active":true,"status":200,"body":{}}'

Configure multiple endpoints atomically:

curl -X POST "$BASE/api/state" \
  -H 'Content-Type: application/json' \
  -d '{"endpoints":[
    {"endpoint":"managedSettings","preset":"empty"},
    {"endpoint":"entitlements","active":false},
    {"endpoint":"token","active":false},
    {"endpoint":"mcpRegistry","active":false}
  ]}'

A preset sets the status and body and enables mocking. Response behavior is configured independently with mode, including when a preset and mode are sent in the same update. Explicit status, body, or active values override the preset. Invalid requests are rejected before any endpoint changes. Supported response modes are json, malformed-json, disconnect, and timeout.

Test fail-closed managed-settings refresh

First serve a successful policy that enables the forced-refresh requirement and sync it into VS Code. Then configure an HTTP error preset or a failing response behavior and sync again. Seeding the requirement first mirrors a real deployment where the cached control self-perpetuates through an outage.

curl -X POST "$BASE/api/state" \
  -H 'Content-Type: application/json' \
  -d '{"endpoint":"managedSettings","preset":"customization-lockdown"}'

# Run "Developer: Sync Account Policy" in VS Code, then choose one:
curl -X POST "$BASE/api/state" -H 'Content-Type: application/json' \
  -d '{"endpoint":"managedSettings","preset":"server-error"}'
curl -X POST "$BASE/api/state" -H 'Content-Type: application/json' \
  -d '{"endpoint":"managedSettings","mode":"malformed-json","status":200}'
curl -X POST "$BASE/api/state" -H 'Content-Type: application/json' \
  -d '{"endpoint":"managedSettings","mode":"disconnect"}'
curl -X POST "$BASE/api/state" -H 'Content-Type: application/json' \
  -d '{"endpoint":"managedSettings","mode":"timeout"}'

These configurations exercise HTTP error, malformed response, immediate network failure, and client-timeout paths respectively. Clear the policy cache if the request does not appear in Live Requests.

Method	Route	Purpose
GET	/api	Discover request shapes and routes
GET	/api/state	Read definitions, presets, and current state
POST	/api/state	Apply one update or an atomic endpoint array
POST	/api/reset	Restore startup endpoint state
GET	/api/schema	Read the managed-settings schema
GET, DELETE	/api/log	Read or clear the request log
DELETE	/api/cache	Clear the managed-settings disk cache
POST	/api/wire	Apply product.overrides.json
POST	/api/unwire	Restore product.overrides.json

Schema and options

The server auto-detects copilot-agent-runtime/schema/managed-settings-schema.json beside the primary VS Code checkout, including from a Git worktree. Override it at startup with --schema or MANAGED_SETTINGS_SCHEMA.

npm run mock-policy-server -- --upstream https://api.ghe.example.com
npm run mock-policy-server -- --schema /path/to/managed-settings-schema.json
npm run mock-policy-server -- --help

Flag	Environment variable	Default
--host	—	127.0.0.1
--upstream	MOCK_POLICY_UPSTREAM	https://api.github.com
--schema	MANAGED_SETTINGS_SCHEMA	Auto-detected sibling checkout