sums001/Windows-Copilot-API: an open-source tool on GitHub for self-hosters

Windows Copilot API — a free, OpenAI-compatible API for your Microsoft Copilot account">

Using your own Microsoft Copilot account. No API key, no credits, no paid plan: it turns the free chat at copilot.microsoft.com into an API you can call from code.

You can use it in two ways:

• 🐍 As a Python library: just call client.chat("Hi"). Supports streaming and multi-turn conversations.
• 🔌 As a local OpenAI-compatible API: runs a server at http://localhost:8000/v1 that speaks the OpenAI format, so the official openai SDK (and any OpenAI-compatible app) works as a drop-in, with localhost in place of OpenAI.

You sign in once with your Microsoft account in a browser; your session is saved and refreshed automatically after that.

Unofficial project. Not affiliated with or endorsed by Microsoft. It automates the consumer Copilot web experience for personal use, so use it responsibly and within Microsoft's terms.

Why use this?

• Free: uses your normal signed-in Copilot, no API billing.
• Drop-in OpenAI replacement: point any OpenAI client at localhost and it just works.
• Works everywhere you're signed in: the signed-in path works even in regions where anonymous Copilot is blocked (e.g. India).
• Streaming + conversations: token-by-token output and multi-turn threads addressed by conversation_id.

Requirements

• Python 3.9+
• A Microsoft account (the free one you use for Copilot is fine)
• Works on Windows, macOS, and Linux

Setup (2 minutes)

# 1. Clone the project
git clone <your-repo-url>
cd Windows-Copilot-API

2. Create and activate a virtual environment

On macOS / Linux:

python3 -m venv venv
source venv/bin/activate

On Windows (PowerShell):

python -m venv venv
venv\Scripts\Activate.ps1

On Windows you may need to allow script execution once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. In cmd.exe activate with venv\Scripts\activate.bat instead.

3. Install dependencies and sign in

# Install dependencies
pip install -r requirements.txt

# Install the browser Playwright needs (one-time)
playwright install chromium

# Sign in once: a browser opens, log into your Microsoft account
python -m copilot login

The browser closes by itself once sign-in is detected — you don't need to press Enter or close it manually. The steps are logged to session/login.log if anything goes wrong. That's it: your session is saved under session/ (git-ignored, never shared) and reused on every run.

💡 You can even skip step 3: the first time you call chat() or start the server, it opens the sign-in browser for you automatically.

🛠️ Run into trouble during setup or your first run? Head to the Troubleshooting section, the bundled diagnostic both fixes common issues (captcha/clearance) and logs a shareable report.

Run with Docker (optional)

Prefer a container? You can run the OpenAI-compatible server in Docker once you've signed in.

Sign in on the host first. The login step above opens a visible browser, which can't run inside the headless container — so run python -m copilot login on your host to populate session/. The container mounts that folder and only does the automatic (headless) token refresh from then on.

docker compose up --build
# -> Copilot OpenAI-compatible API on http://localhost:8000

The docker-compose.yml maps port 8000 and bind-mounts your session/ so the login persists across restarts. Tune RATE_LIMIT_RPM / RATE_LIMIT_BURST there. To run without Compose, build and pass the same bindings by hand:

docker build -t windows-copilot-api .
docker run --rm -p 8000:8000 -v "$(pwd)/session:/app/session" windows-copilot-api

Usage 1: In Python (no server)

The simplest way if your code is already Python.

from copilot import CopilotClient

client = CopilotClient()                 # loads your signed-in session

# Get a full reply
reply = client.chat("Say hello in one short sentence.")
print(reply.text)

# Continue the SAME conversation — pass the id back
reply2 = client.chat("And now in French?", reply.conversation_id)
print(reply2.text)

# Stream the answer as it's typed
for chunk in client.stream("Tell me a short joke"):
    print(chunk, end="", flush=True)

chat() returns the full text plus a conversation_id; pass that id back to keep the thread going, or omit it to start fresh. stream() yields the reply piece by piece.

👉 More: examples/01_direct_chat.py, 02_direct_conversation.py, 03_direct_stream.py

Usage 2: As an OpenAI-compatible server

Start a local server that speaks the OpenAI API, so existing OpenAI tools and SDKs work unchanged.

python app.py
# -> Copilot OpenAI-compatible API on http://127.0.0.1:8000

Then point any OpenAI client at it (the API key is required by the SDK but ignored):

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="unused")

resp = client.chat.completions.create(
    model="copilot",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

Or call it with plain HTTP / curl:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

Endpoints

Change the address with env vars: HOST=0.0.0.0 PORT=8080 python app.py, or run uvicorn server.api:app --host 0.0.0.0 --port 8080.

👉 More: examples/04_server_http.py, 05_server_stream.py, 06_server_openai_sdk.py

Command line

python -m copilot login          # sign in and save the session
python -m copilot ask "Hello!"   # quick one-shot question

Concurrency & stress test

The server bridges a single signed-in Copilot account, and Copilot's chat socket doesn't tolerate concurrent conversations from one process. So the server serializes upstream calls: parallel HTTP requests queue behind a lock and run one at a time (see server/api.py). This is intentional, and it means throughput is sequential, not parallel.

You can measure where it breaks with the included stress test, which fires a batch of simultaneous requests and doubles the batch size every successful round until the first error:

# Start the server in one terminal
python app.py

# Ramp concurrency in another (1 → 2 → 4 → 8 → …)
python tests/stress.py
python tests/stress.py --max 64 --timeout 120 --url http://localhost:8000

Sample run (one signed-in account):

Highest fully-successful concurrency: 4. Wall time roughly doubles each round while minimum latency stays flat (~3.5s) — the signature of a serialized queue: one request runs immediately, the rest wait their turn. The failure at 8 is an upstream 502 (Copilot rejecting requests under load), not a server crash or timeout — so the exact break point is flaky and may vary between runs.

Takeaway: keep concurrent in-flight requests low (≈ 1–4). This is a personal bridge, not a high-throughput gateway — and please don't hammer your account.

Rate limiting

Concurrency (above) is how many at once; the rate limit is how many per minute, sustained. Microsoft publishes none for consumer Copilot, so the bridge enforces a self-imposed one with a token bucket: it caps accepted requests per minute and returns a standard 429 + Retry-After when you exceed it. Two env vars tune it:

RATE_LIMIT_RPM=20 RATE_LIMIT_BURST=5 python app.py   # raise it; 0 to disable

The default 12 rpm sits safely below the ~15 rpm where a single account starts seeing upstream 502s. To find your ceiling, run the server with the limiter off (RATE_LIMIT_RPM=0) and push the probe until failures appear:

python tests/ratelimit.py --rpm 20 --minutes 3

On the client side, use exponential backoff. Both 429 (bridge limit) and the occasional 502 (Copilot upstream hiccup) are transient — retry with growing delays (e.g. 1s, 2s, 4s) and they almost always clear. The official openai SDK does this automatically and honours Retry-After; with plain HTTP, add a few retries yourself.

Project layout

Notes & limitations

• Sign in once, then reuse. The cached token refreshes automatically; you only re-sign-in if the session fully expires.
• No daily limit, but be reasonable. Microsoft doesn't impose a daily chat cap, but please use it in moderation, and don't spam or hammer it with automated bulk requests.
• One model. Copilot has no model picker, so the server advertises a single model named copilot.
• Roughly GPT-4 class. On GPQA Diamond (198 graduate-level questions, closed-book) it scores 40.9%, which puts it in the GPT-4 family rather than the reasoning tier (o1/o3). Measured with tests/gpqa_bench.py.
• Your session is private. Everything in session/ (cookies + token) stays on your machine and is git-ignored.

Troubleshooting

Hit an error? Run the diagnostic first — it both fixes and logs.

python tests/diagnostic.py                # browser capture + captcha fix + report
python tests/diagnostic.py --report-only  # headless/VPS: report only, no browser

The default run opens your signed-in browser and asks you to send one short message. That single action does two things:

• Fixes captcha: it drives a real browser on the same session/profile/ the bridge uses, so passing any "verify you're human" check earns a fresh cf_clearance cookie. When the turn completes the tool snapshots that session (cookies + token) into session/token.json, so the pure-HTTP driver adopts the clearance immediately.
• Captures the protocol to session/ws_capture.log. A clean turn goes setOptions → send → appendText… → done; a {"event":"challenge", "method":"cloudflare",…} frame means Cloudflare gated you (now cleared).

It also writes session/diagnostic_report.txt — environment, the shape of your session (cookie names + token length, never the values), a live chat probe, and redacted log tails. Both files are safe to share: access tokens, cookies, OAuth codes, and emails are redacted before anything is written. Attach diagnostic_report.txt to a GitHub issue (skim it first) and the cause is usually obvious.

On a headless server/VPS you can't open the browser, so the captcha fix isn't available there — pass --report-only, then do the clearance step on a machine with a display (or route traffic through a residential connection, e.g. a home-PC exit node) since datacenter IPs are where Cloudflare withholds clearance and you see RuntimeError: Copilot error: invalid-event.