Skip to main content

Google Colab

Google Colab exposes a Jupyter-compatible kernel behind an authenticating proxy. Use ColabKernelClient to connect to a kernel that is already running in Colab.

This client reuses an existing Colab runtime; it does not create a Colab runtime from scratch.

You need three values to connect:

  • server_url
  • kernel_id
  • proxy_token

All three are available in Colab's channels WebSocket URL.

Option A: Connect With Explicit Values​

from jupyter_kernel_client import ColabKernelClient

kernel = ColabKernelClient(
    server_url="https://<colab-host>",
    kernel_id="<kernel_id>",
    proxy_token="<proxy_token>",
)
kernel.start()
reply = kernel.execute("x = 1")
print(reply)
# Disconnect only; do not shut down shared Colab runtime kernels.
kernel.stop(shutdown_kernel=False)

Option B: Connect From Channels URL​

from jupyter_kernel_client import ColabKernelClient

channels_url = (
    "wss://<colab-host>/api/kernels/<kernel_id>/channels"
    "?session_id=<...>&colab-runtime-proxy-token=<proxy_token>&colab-client-agent=web"
)

with ColabKernelClient.from_channels_url(channels_url) as kernel:
    reply = kernel.execute("x = 1 + 1; print(x)")
    print(reply)

You can also parse values directly:

from jupyter_kernel_client import parse_colab_channels_url

server_url, kernel_id, proxy_token = parse_colab_channels_url(channels_url)

ColabKernelClient forwards the proxy token as both the X-Colab-Runtime-Proxy-Token HTTP header and the colab-runtime-proxy-token WebSocket query parameter.

How To Obtain The Colab Channels URL​

The server_url, kernel_id, and proxy_token are in the WebSocket channels URL used by Colab itself:

wss://<host>/api/kernels/<kernel_id>/channels?session_id=<...>&colab-runtime-proxy-token=<proxy_token>&colab-client-agent=web

Values are tied to your browser session and are short-lived.

  1. Open your notebook on https://colab.research.google.com and connect a runtime.
  2. Open DevTools (F12) and switch to Network with the WS filter.
  3. Run a cell to generate traffic.
  4. Open the .../api/kernels/<kernel_id>/channels?... request and copy the full URL.

If you extract values manually:

  • server_url: scheme+host before /api/kernels (use https://)
  • kernel_id: UUID path segment after /api/kernels/
  • proxy_token: colab-runtime-proxy-token query parameter

Consumer Colab does not provide a public API key based flow to create runtimes from standalone scripts.

For a true programmatic runtime provisioning flow, use Colab Enterprise on Google Cloud.