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:
| Setting | Clients it routes | Who controls it |
|---|---|---|
Per-user copilotUrl (step 5) | Copilot CLI only | The developer, who can remove it |
Managed copilotInferenceUrl (step 6) | Copilot CLI, VS Code agent sessions in the Copilot harness, and the GitHub Copilot app | Your 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
- Deploy Watcher with
auth.mode: proxyusing the Kubernetes guide, or configure an existing deployment for proxy authentication. - 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. - 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.
- Choose a trusted HTTPS hostname for Copilot traffic and a private route from the gateway to Watcher's API.
- 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 examplegithub: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:
- 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. - Add
WATCHER_PROXY_AUTH_TOKENto Watcher's own Secret (watcher-externalin the Kubernetes guide). The chart loads it asXYLON_PROXY_AUTH_TOKEN. - Restart the API (
deployment/xylon-apion 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 withmodel_info.mode: responsesso LiteLLM also keeps their Responses format. - Copilot sends
reasoning_effortto Gemini models, so keepallowed_openai_params: [reasoning_effort]on each Gemini entry, as the packagedgemini-*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:
| Key | Value |
|---|---|
DATABASE_URL | postgresql://USER:PASSWORD@HOST:5432/DBNAME, with URL-encoded credentials. |
LITELLM_MASTER_KEY | A generated secret for LiteLLM's internal configuration. It does not admit developers to the native endpoint. |
WATCHER_PROXY_AUTH_TOKEN | The 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:
-
Validate the gateway as described in step 5.
-
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.
-
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:
Client Minimum version Copilot CLI 1.0.106 VS Code 1.146.0 GitHub Copilot app 1.2.0 -
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:
| OS | Path |
|---|---|
| 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.
-
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/shset -eudir="/Library/Application Support/GitHubCopilot"tmp="$(mktemp)"trap 'rm -f "$tmp"' EXITprintf '%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" -
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:
-
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" -
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 loadedwithcopilotInferenceUrlin itskeyslist. The message says device MDM even when the setting comes from the file. If a client logshas an unsupported or malformed value and was ignoredforcopilotInferenceUrl, the client is too old or the URL is invalid. -
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.