A few years ago, during my final year project, I got my Google account suspended for months.
The crime? I was living in the "two-tab hell" every ML developer knows: my Git repo and project in VS Code, and my GPU-powered notebook in a Chrome tab. The workflow was killing me. I'd !git pull in a cell, manually upload datasets, and scp my model checkpoints back and forth. It was slow and painful.
So, I found a hack. A script that used colab-ssh and ngrok (or Cloudflare) to create a reverse tunnel from the Colab VM back to my local machine. I could finally plug my local VS Code directly into the Colab runtime. It was magic... right up until Google's security systems (rightfully) saw this sketchy, unauthenticated backdoor and locked my account for violating the Terms of Service.
Fast forward to now. I see the official announcement: Google Colab is Coming to VS Code.
My first thought wasn't "finally!" It was, "Wait... what?"
Did they just whitelist the exact ngrok hack that got me suspended? Or did they build something else? I had to know. As an open-source contributor, I couldn't just use it; I had to pop the hood and see the engine. I cloned the colab-vscode repo to find out.
Here’s the technical decode of what I found.
The first thing I found is that the extension
Is a brilliant Adapter. It doesn't re-implement a notebook interface it’s a "plugin for a plugin."
-
File:
package.json What it does: It lists
"ms-toolsai.jupyter"as anextensionDependency. This means the Colab extension is just a data source for the official Microsoft Jupyter extension.File:
src/jupyter/provider.tsWhat it does: The
ColabJupyterServerProviderclass is the core of the adapter. It implements theJupyterServerProviderinterface that the Microsoft extension expects. When you click "Select Kernel," the Jupyter extension asks this class, "Hey, got any servers?" and this class is responsible for replying.
This is a key insight: they didn't build a new car; they just built a universal adapter that lets you plug Colab's proprietary engine into the "Jupyter" car we all already drive.
The "Front Door"-- How They Solved the ngrok Problem
This was the part I cared about. How do you connect without getting banned?
My Hack: I used
ngrokto create a reverse proxy. This pokes a hole out of Google's secure VM to a public URL. This is the "backdoor" that got me banned.The Official Way: I found the answer in
src/auth/flows/loopback.ts. They built the complete opposite: a secure, local-only loopback flow.
When you click "Sign In," it doesn't run a tunnel script.
- It spins up a tiny, temporary
http.createServer()on127.0.0.1at a random port. - It opens your browser to the real Google OAuth page, but it passes a
redirect_uripointing tohttp://127.0.0.1:[your_port]. - When you sign in, Google redirects your browser back to your own machine.
- The
Handlerinloopback.tscatches this one request, grabs the authorizationcodefrom the URL, and immediately shuts the server down.
This is why it's secure and allowed. It's not a public tunnel. It's a "key exchange" that proves you are the physical user on that exact machine. The refreshToken it gets is then stored securely in VS Code's native SecretStorage via src/auth/storage.ts.
The "Connection"-It's Not SSH, It's an API
So, my hack used SSH. How do they connect?
The answer is in src/colab/client.ts. The extension doesn't use SSH at all. It's all HTTPS.
When you click "New Colab Server," the AssignmentManager (src/jupyter/assignments.ts) calls the ColabClient. This client makes an authenticated POST request to an internal Google API: /tun/m/assign.
This is the real "front door." Google's backend verifies your accessToken (your "ID badge" from the auth step) and sends back a JSON object. The src/colab/api.ts file defines the schema for this, and it's the holy grail: RuntimeProxyInfo.
This RuntimeProxyInfo object is the "key to the runtime" I was missing all those years ago. It contains:
- A unique, temporary
url(likehttps_a-b-c.colab.googleusercontent.com). - A separate, temporary
tokenfor that specific runtime.
When the Jupyter extension tries to run a cell, the colabProxyFetch function (src/jupyter/assignments.ts) intercepts the request and injects this new token into a custom HTTP header: X-Colab-Runtime-Proxy-Token.
We're not hacking into a VM's Jupyter process. We're an authenticated guest talking to a first-party, managed API proxy.
The "Aha!" Bonus Finds
I kept digging and found two more gems that show the level of thought that went into this.
1. The "Keep-Alive" Hack is Gone.
I used to run while True: time.sleep(60) in a cell. It was dumb. In src/colab/keep-alive.ts, they have a ServerKeepAliveController. It runs a background task every 5 minutes that just calls ColabClient.sendKeepAlive. This is a simple API ping to /tun/m/.../keep-alive/ that resets the idle timer on Google's backend. Clean.
If you are idle, it even pops the "Server is idle" notification in VS Code, and if you click "Cancel" (as in, "cancel the disconnect"), it keeps the pings going.
2. The "LSP Fix" is Brilliant.
This is my favorite part. The Python Language Server (Pylance) has no idea what !pip install or %matplotlib means, so it draws red squiggles under them.
So, did the Colab team write their own Language Server? Nope.
In src/lsp/middleware.ts, they register "LSP middleware." This is code that sits between the Python LSP and your editor. The function filterNonIPythonDiagnostics intercepts all diagnostics (errors) before they're rendered.
It reads the text of the line with the error. If that line starts with ! or %, it just... throws the error away.
It's a simple, perfect, and invisible fix.
The Verdict
So, no. Google didn't just allow the tunnel hack. They built the real, secure, and robust system we were all trying to build ourselves.
I was banned for trying to pick the lock. The official team built a proper front door with an authenticated doorman and gave us all a key. It's the exact workflow I always wanted, and I don't even have to risk my account for it. Well done, team.
Top comments (0)