Skip to main content
Working with an agent? Give them a link to this page as markdown.

Native Copilot through LiteLLM

Use the LiteLLM example to send native GitHub Copilot requests through Watcher gateway hooks. The gateway holds each model-proposed client tool call until Watcher returns a decision. Your organization's enforcement mode decides whether a denial withholds the call. Developers keep their GitHub login and Copilot seat. They do not need a LiteLLM key or a Watcher client for this path.

The example is source you integrate and operate. You choose the LiteLLM version and image, and adapt the deployment reference to your environment. It was tested with Copilot CLI 1.0.109 and LiteLLM 1.108.3. It serves Auto model selection and three native HTTP inference formats:

  • OpenAI Responses, for GPT, Grok and MAI models.
  • Anthropic Messages, for Claude models.
  • Chat Completions, for Gemini models.

Two Copilot settings send clients to the gateway:

SettingClients it routesWho controls it
Per-user copilotUrl (step 5)Copilot CLI onlyThe developer, who can remove it
Managed copilotInferenceUrl (step 6)Copilot CLI, VS Code agent sessions in the Copilot harness, and the GitHub Copilot appYour device management; user settings cannot override it

Requests to BYOK providers do not pass through the gateway. The gateway serves github.com accounts only, not GitHub Enterprise hosts. It refuses WebSocket connections; clients then fall back to HTTP inference, which it checks. A nested subagent, started by another subagent, is checked and recorded like a direct child, linked to the subagent that started it, but nested subagents have not been tested live.

The gateway keeps provider-run searches out of the copy sent to Watcher, so grouped tool-server calls also work with an older Watcher server. Native Copilot uses the same <server>-<tool> name for plain and grouped calls in policy rules, recorded calls and gateway notices, for example desk-crm_whoami.

1. Collect the inputs​

  1. Deploy Watcher with auth.mode: proxy using the Kubernetes guide, or configure an existing deployment for proxy authentication.
  2. Obtain the SDK source archive matching your Watcher release. Get the examples describes the archive. Extract it and locate sdk/examples/litellm, which contains the example and its Dockerfile. The self-host release ZIP includes the Helm chart alongside Docker Compose. The SDK source is a separate archive.
  3. Provide a separate PostgreSQL database for LiteLLM. Its database user must own the database and be able to run migrations. All gateway replicas share it. Do not use Watcher's database for the gateway tables.
  4. Choose a trusted HTTPS hostname for Copilot traffic and a private route from the gateway to Watcher's API.
  5. Decide whether to map GitHub accounts to company email addresses. The mapping is optional. Without an entry, Watcher assigns the developer's sessions to github:<numeric-id>, for example github:123456. To share an identity with browser sign-in, map the account to the email address your sign-in proxy sends to Watcher. Verify the numeric ID through GitHub's authenticated user API and the email through your company directory. Do not infer the link from a public GitHub profile.

For Azure, the browser-facing proxy can authenticate users with Entra ID and send their email and role to Watcher. The gateway independently verifies the GitHub account and sends the mapped email, or the github:<numeric-id> identity when no entry exists. It does not discover Entra accounts or perform an Entra login for Copilot. A developer signed in through Entra does not own sessions recorded under their GitHub identity. Reading those sessions requires the usual session access permissions or an approved access request.

The mapping is not an access allowlist. Any account whose github.com credential passes verification can reach the native routes. GitHub checks Copilot entitlement and model access upstream. Restrict access to the gateway through your network controls if only selected users may connect. Adding, changing or removing an email mapping does not reassign existing sessions. Continuing a conversation after its identity changes can create a separate Watcher session under the new identity.

The gateway calls Watcher as a trusted proxy, using a server-held WATCHER_PROXY_AUTH_TOKEN that must match Watcher's proxy token. Once Watcher has this token, it rejects proxy-mode requests that do not carry it, including requests from your browser-facing authentication proxy. To add the token to an existing deployment without an outage, work in this order:

  1. Configure the browser-facing authentication proxy to send the token in X-Auth-Proxy-Token, with its trusted identity and role headers. Roll out that change and verify that existing access still works.
  2. Add WATCHER_PROXY_AUTH_TOKEN to Watcher's own Secret (watcher-external in the Kubernetes guide). The chart loads it as XYLON_PROXY_AUTH_TOKEN.
  3. Restart the API (deployment/xylon-api on Kubernetes) and verify access through the proxy again.

This token is separate from WATCHER_INTERNAL_AUTH_TOKEN. Keep it in secret storage, restrict private API access to trusted callers, and never give it to developers. Watcher's own model access for grading stays separate from each developer's Copilot model access.

Optional: manage identity mappings in LiteLLM​

The reference stores optional GitHub-ID-to-company-email mappings in litellm.users YAML. Updating these values rolls the gateway pods to load the new mapping. Leave it empty to use GitHub IDs for all developers.

You can instead adapt the example to read mappings from LiteLLM user records in its shared database. This option is not built into the shipped example or chart. It requires replacing the gateway's YAML lookup and adapting the chart's mapping file configuration. Choose it explicitly before adapting the source.

In a dedicated deployment, records can use user_id: github:<numeric-id> and user_email for the verified company email. Create records through /user/new with auto_create_key: false and update them through /user/update. Developers still use their own GitHub login and Copilot seat, without a LiteLLM key.

The native gateway does not expose these management routes. Provide private, operator-only access to them. LiteLLM allows users to edit their own email, so do not trust a self-service email field for this mapping. An Entra login alone does not verify which GitHub account belongs to an employee. See LiteLLM's user management documentation.

Have each gateway replica read current mappings from the shared database and retain GitHub-ID identities for unmapped accounts. Before using the adapted deployment, verify that adding, changing and removing a mapping takes effect on both replicas without a restart. Also run the Copilot validation prompt below.

2. Build your gateway image​

From the extracted sdk directory:

docker build -f examples/litellm/Dockerfile \
-t your-registry.example.com/watcher-litellm:your-tag .

When your cluster nodes use another CPU architecture than the build machine, for example amd64 nodes and an Apple Silicon Mac, build with docker buildx build --platform linux/amd64 and the same arguments.

Push the image to your registry and record its digest. The Dockerfile installs the SDK, the example and the runtime dependencies from the example's locked, hashed versions. It generates the Prisma database client while building.

The packaged model list in copilot.yaml uses the github_copilot/ provider. It names tested GPT, Grok and MAI models. The gpt-*, claude-* and gemini-* wildcard entries route other GPT, Claude and Gemini models. GitHub's model policy for each account decides which models a developer can use; the gateway's list only decides which models it routes. Auto and Copilot's built-in subagents can choose a model other than the one the developer selected. A request for a model the list does not route fails.

To customize the model list, extract the packaged configuration:

docker run --rm --entrypoint watcher-litellm-copilot-config \
your-registry.example.com/watcher-litellm:your-tag > copilot.yaml

Edit model_list for your models:

  • Native GPT requests keep the Responses format, including models routed through gpt-*. Give Grok and MAI models their own entries with model_info.mode: responses so LiteLLM also keeps their Responses format.
  • Copilot sends reasoning_effort to Gemini models, so keep allowed_openai_params: [reasoning_effort] on each Gemini entry, as the packaged gemini-* entry does.
  • For a Claude model that LiteLLM's catalog does not list, give it its own entry with model_info.supports_adaptive_thinking: true; otherwise LiteLLM drops the thinking settings Copilot sends.

Preserve both callbacks (watcher_litellm.copilot.provider_callback and watcher_litellm.callback.watcher_callback), custom authentication, credential configuration and the three discovery/selection pass-throughs. Inference must use the normal Copilot provider so Watcher can withhold tools. Do not enable LiteLLM features that run tools inside the gateway, such as web search interception or MCP servers. Do not add an inference pass-through. Keep message, spend and HTTP body logging disabled. Ingress logging must not capture the Authorization header or the Copilot-Session-Token header, which carries Copilot's Auto model-selection token.

3. Enable the Kubernetes reference​

Skip this section for an existing non-Kubernetes LiteLLM deployment. Follow the example README's native setup to configure its environment, migrations and watcher_litellm.copilot:app ASGI entry point.

Create a Secret named litellm-credentials in the Watcher release namespace using your secret manager. It needs these keys:

KeyValue
DATABASE_URLpostgresql://USER:PASSWORD@HOST:5432/DBNAME, with URL-encoded credentials.
LITELLM_MASTER_KEYA generated secret for LiteLLM's internal configuration. It does not admit developers to the native endpoint.
WATCHER_PROXY_AUTH_TOKENThe same nonempty token used by Watcher and its trusted authentication proxy.

Add these values to your Watcher values file. Replace the image digest with your own:

auth:
mode: proxy
litellm:
enabled: true
image: your-registry.example.com/watcher-litellm@sha256:YOUR_DIGEST
existingSecret: litellm-credentials
imagePullSecrets: [gateway-registry]
replicas: 2
users: {}

Create gateway-registry as a pull Secret for your gateway image registry in the release namespace. Set imagePullSecrets: [] only if nodes already have access. This setting is separate from Watcher's image.pullSecrets.

To match selected developers to their browser sign-in identities, replace users: {} with a partial or complete mapping:

litellm:
users:
"123456": developer@example.com

Keep numeric GitHub IDs quoted. Each mapped email must contain only ASCII characters. An omitted or empty users map uses GitHub-ID identities for all accounts. A partial map uses emails for listed accounts and GitHub IDs for the rest. Model selection and request-body fields cannot choose the Watcher owner. Sessions are scoped to the authenticated account.

Lint and render the chart with these additional values as the Kubernetes guide describes. To add the gateway to your existing Watcher release, apply the full values file with:

helm upgrade watcher "$WATCHER_CHART" \
--kube-context "$WATCHER_CONTEXT" --namespace "$WATCHER_NAMESPACE" \
-f watcher-values.yaml --timeout 10m

Use the guide's helm install command only for a new Watcher release. Keep your existing configuration flags on each upgrade, including --set-file serverConfig=server-config.yaml if used. If you customized the model list, also pass --set-file litellm.config=copilot.yaml on every install and upgrade.

The chart runs watcher-litellm-migrate before installing or upgrading workloads. That Job migrates LiteLLM and its task mapping. The two serving replicas do not run migrations. The database must be reachable before the pre-install Job starts, so use a provisioned database outside this release.

Check the migration and replicas:

kubectl --context "$WATCHER_CONTEXT" -n "$WATCHER_NAMESPACE" get job watcher-litellm-migrate
kubectl --context "$WATCHER_CONTEXT" -n "$WATCHER_NAMESPACE" rollout status deployment/watcher-litellm
kubectl --context "$WATCHER_CONTEXT" -n "$WATCHER_NAMESPACE" get pods -l app.kubernetes.io/component=litellm

Expect a completed Job and two ready replicas. On a failed migration, inspect its logs and correct the cause before retrying the release. Keep task-mapping data across restarts and upgrades; deleting it breaks existing resumes and parent relationships. Back it up with the LiteLLM database. The mapping stores SHA-256 task-prompt digests and spawning call IDs, but no prompt text or GitHub credentials. On upgrades, the chart runs its migration Job before new replicas start. For a direct launch, rerun watcher-litellm-copilot-migrate first; the additive schema changes remain compatible with old replicas.

4. Route native Copilot requests​

Route your Copilot hostname's /copilot/ prefix to the private Service watcher-litellm:4000. Preserve that prefix, request bodies, authorization, native session/task headers, and streaming responses. Allow request bodies up to 32 MiB, the gateway's own limit. The chart does not create this ingress. The gateway must reach api.github.com, to verify each account, and api.githubcopilot.com, for discovery and inference. The gateway authenticates Copilot's GitHub bearer credential itself. A browser sign-in redirect or an Entra bearer requirement on this route prevents native Copilot authentication.

The reference gateway calls the private Watcher API at http://xylon-api:8000/api. With networkPolicy.enabled: true, the API ingress policy admits gateway pods from the same release. Keep Watcher's browser and API hostname, which serves Watcher Analyzer, behind its identity proxy. The Copilot route and Watcher's hostname use different authentication; both can use your normal TLS and network controls. Do not expose other LiteLLM inference paths or a second unmonitored route to the model provider as part of this gateway.

For local tests, run any proxy or kubectl port-forward under a service, container or separate persistent terminal session. It must survive the setup shell and agent exiting. A background job owned by that shell is not a persistent route. Before handover, verify Watcher's authenticated /api/v1/health endpoint and a native Copilot request from a separate shell. Save the commands to start and stop these access processes.

The native adapter permits only /copilot/meta, /copilot/models, /copilot/auto, /copilot/responses, /copilot/v1/messages and /copilot/chat/completions, plus health probes. LiteLLM forwards the first three to GitHub for discovery and selection. Inference passes through the Watcher callback before any executable tool call reaches the client. Each inference format accepts only its own request fields and tools that the client runs. The gateway refuses provider-hosted tools, such as hosted web search, because they would run before Watcher sees the response. A refused request is logged as copilot_request_refused with the reason and number of rejected fields, headers or tool types. Names and values stay out of logs.

When a session has many tools, for example from several MCP servers, Copilot can defer its MCP and other external tools in Responses requests. It groups them by server and adds a tool search. The Responses route accepts both. GitHub's search only loads definitions of tools the request already lists. Any tool the model then calls waits for a Watcher decision under its Copilot name. Watcher's record leaves out the search step. The Anthropic Messages and Chat Completions routes accept only ordinary client tools, so the gateway refuses a tool search or tool group there. Its logs contain the refusal reason and number of rejected types. In testing, a Claude session with tool search turned on was accepted and answered normally. Claude calls to deferred MCP tools and Gemini sessions with deferred tools have not been tested.

Some tool-server names are reserved by the provider. A server named notes, for example, can prevent a child from starting with an error that its function is not allowed in the reserved namespace. Rename that server in Copilot's MCP configuration and retry.

Calls that Copilot creates itself cannot be judged before execution by a model gateway. For example, when a background child finishes or fails, Copilot creates and runs read_agent without a model request. These calls can appear in later conversation history as not evaluated.

5. Connect and validate one developer​

Have the developer sign in to the normal Copilot CLI with an authorized GitHub account. Preserve their settings and add this value to ~/.copilot/settings.json, or $COPILOT_HOME/settings.json:

{"copilotUrl": "https://copilot.example.com/copilot"}

Only the Copilot CLI reads this per-user setting, and the developer can remove it. To route VS Code and the GitHub Copilot app, or to enforce the gateway on managed devices, use step 6.

This path does not require COPILOT_PROVIDER_WIRE_API, BYOK settings or a custom launcher. Copilot sends its native session, task and parent IDs. The gateway uses them to retain the root session across resume and record each direct child separately with a parent link. Across the supported inference formats, a new child also links to the parent task call when its initial prompt has one exact match. This covers sync and background children. If the prompt is unknown or repeated, the child keeps only its parent link. Once assigned, the spawning call stays fixed across resume. New children of a parent task handled by an older replica keep parent-only links. Start new sessions after every replica has been upgraded to get spawning links throughout the session.

Parent and spawning-call links are recorded after each captured exchange. Link failures do not fail the response or change Watcher's tool-call decision. Later child captures retry them, including when the parent's messages arrive late. If no further child capture arrives, the link can remain missing. An unknown parent task, conflicting ancestry or unavailable gateway task storage still prevents generation.

Follow GitHub's MCP setup instructions for Copilot CLI to add tool servers. Grouped tools and direct child sessions need no extra gateway setting.

This gateway does not require the Watcher client on the developer's machine. If the client also monitors Copilot, it can record and evaluate the same work through its own hooks. For gateway-only Copilot monitoring, the operator can authorize watcher agents disable copilot; confirm the result with watcher agents list. This leaves the client's other agent integrations in place. Keep required client monitoring enabled where device policy mandates it, and use the validation prompt's isolated test profile to check the gateway.

Run the Copilot validation prompt in a disposable Watcher deployment with the intended configuration before connecting developers to your own deployment. Its test policy applies to the whole organization, including other Watcher clients; a separate gateway pointing to the same Watcher does not isolate it. Do not run its policy-changing cases on a shared deployment. It checks actual tool effects, Watcher decisions and parent/child records, not just a successful model answer. Restore the deployment's original policy afterwards.

Check grouped calls in the same disposable deployment with Copilot CLI 1.0.109 and gpt-6-luna. Connect an MCP server that exposes 16 tools and ask Copilot for one harmless read from it. In the Analyzer, confirm that a LiteLLM session in the Gateway category records the call as <server>-<tool> with a Watcher decision. The gateway checks each client call even when the Watcher server does not accept provider-run search items.

One real account suffices for the deployment checks. The example's automated tests cover isolation between controlled accounts with identical session and task IDs; that coverage is not a live two-user test.

6. Enforce the gateway on managed devices​

Copilot's copilotInferenceUrl managed setting sends model requests from the Copilot CLI, VS Code and the GitHub Copilot app to the gateway. User and repository settings cannot override it, including a per-user copilotUrl. Sign-in, model discovery and other GitHub services keep their usual endpoints. The setting does not affect BYOK providers, so their requests do not pass through the gateway. GitHub's managed-settings reference does not list this setting yet, so repeat the verification below after you update clients.

In VS Code, the setting covers agent sessions in the Copilot harness, the default for new sessions. Local harness sessions and other VS Code Copilot features are outside this configuration.

Before you deploy the setting:

  1. Validate the gateway as described in step 5.

  2. Choose the optional email mappings described in steps 1 and 3. Without a mapping, a developer's Entra or other email-based browser login does not own their GitHub-ID sessions. Confirm that your reviewers have the session access they need.

  3. Update VS Code, the Copilot CLI and the GitHub Copilot app on every device. Older versions ignore the setting and send model requests straight to GitHub, without an error. Keep every client at or above these versions:

    ClientMinimum version
    Copilot CLI1.0.106
    VS Code1.146.0
    GitHub Copilot app1.2.0
  4. Tell developers which models they can use. Only models in the gateway's model list work (see step 2). The model picker still lists every model the account can use, because model discovery stays with GitHub.

Deploy this Copilot managed-settings document, using your gateway URL ending in /copilot (the copilotUrl value from step 5):

{"copilotInferenceUrl": "https://copilot.example.com/copilot"}

If you already deploy Copilot managed settings, add the key to that document instead of replacing it. Do not also set copilotInferenceUrl in another channel, such as GitHub's server-managed settings. A different or blank value there can replace yours.

The file-based locations are:

OSPath
macOS/Library/Application Support/GitHubCopilot/managed-settings.json
Windows%ProgramFiles%\GitHubCopilot\managed-settings.json
Linux/etc/github-copilot/managed-settings.json

On macOS and Linux, make the file a regular file owned by root and not writable by group or others. Copilot rejects a symlink. Root ownership stops ordinary users from changing the setting; local administrators can still remove it. Developers must restart each Copilot client to load a new or changed file. GitHub's deployment guide also covers native MDM delivery.

Example: Microsoft Intune on macOS​

This example writes the macOS file with an Intune shell script. On Windows and Linux, deliver the same document to the path in the table above.

  1. Save this script with your gateway URL. Each run replaces the whole file, so if you deploy other Copilot managed settings, add them to the JSON document in the script:

    #!/bin/sh
    set -eu
    dir="/Library/Application Support/GitHubCopilot"
    tmp="$(mktemp)"
    trap 'rm -f "$tmp"' EXIT
    printf '%s\n' '{"copilotInferenceUrl": "https://copilot.example.com/copilot"}' > "$tmp"
    /usr/bin/install -d -o root -g wheel -m 0755 "$dir"
    /usr/bin/install -o root -g wheel -m 0644 "$tmp" "$dir/managed-settings.json"
  2. In the Microsoft Intune admin center, add it as a macOS shell script. Set Run script as signed-in user to No, so it runs as root. Set Script frequency to a recurring interval, so later runs restore a changed file. Assign it to the device groups that must use the gateway. See Microsoft's macOS shell script guide.

The Intune management agent checks for new scripts about every eight hours. To check sooner on a test Mac, open Company Portal, select the device and select Check settings.

Verify the rollout​

On a test device that has received the file, without the per-user copilotUrl from step 5:

  1. Confirm that root owns the file and its directory, and that neither is writable by group or others:

    ls -ld "/Library/Application Support/GitHubCopilot" \
    "/Library/Application Support/GitHubCopilot/managed-settings.json"
  2. Quit and reopen each Copilot client. Each client's Copilot runtime writes logs to ~/.copilot/logs/, or $COPILOT_HOME/logs/. Search the logs written since the restart, for example the five newest:

    grep -H copilotInferenceUrl $(ls -t ~/.copilot/logs/process-*.log | head -n 5)

    A loaded setting logs [managedSettings] device MDM policy loaded with copilotInferenceUrl in its keys list. The message says device MDM even when the setting comes from the file. If a client logs has an unsupported or malformed value and was ignored for copilotInferenceUrl, the client is too old or the URL is invalid.

  3. Send a prompt from each client using a model the gateway serves. In VS Code, use an agent session in the Copilot harness. In Watcher Analyzer, confirm each session has the LiteLLM capture source in the Gateway category and the expected owner: the developer's mapped company email or github:<numeric-id> when no mapping exists.