Colab lets you connect to a local runtime. This allows you to execute code on your local hardware.
Make sure you trust the authors of any notebook before executing it. With a local connection, the code you execute can read, write, and delete files on your computer.
Connecting to a runtime on your local machine can provide many benefits. With these benefits come serious potential risks. By connecting to a local runtime, you are allowing the Colab frontend to execute code in the notebook using the local resources on your machine. This means that the notebook could:
Invoke arbitrary commands (e.g. "
rm -rf /")
- Access the local file system
- Run malicious content on your machine
Before attempting to connect to a local runtime, make sure you trust the authors of the notebook and ensure you understand what code is being executed. For more information on the Jupyter notebook server's security model, consult Jupyter's documentation.
Step 1: Start a runtime
You can either run Jupyter directly or use Colab's Docker image. The Docker image includes packages found in our hosted runtime environments (https://colab.research.google.com) and enables some UI features such as debugging and the resource utilization monitor. Packages (files in general) installed on your local machine are however not available by default.
Option 1. Colab Docker runtime image
Install Docker on your local machine. Start a runtime:
docker run -p 127.0.0.1:8888:8080 us-docker.pkg.dev/colab-images/public/runtime
The URL to use in the next step will be http://localhost:8888?token=[token] with [token] replaced by the token value provided in the output.
Option 2. Jupyter runtime
Install Jupyter on your local machine. New notebook servers are started normally, though you will need to set a flag to explicitly trust WebSocket connections from the Colab frontend.
jupyter notebook \ --NotebookApp.allow_origin='https://colab.research.google.com' \ --port=8888 \ --NotebookApp.port_retries=0
Once the server has started, it will print a message with the initial backend URL used for authentication. Make a copy of this URL as you'll need to provide this in the next step.
Step 2: Connect to the local runtime
In Colab, click the "Connect" button and select "Connect to local runtime...". Enter the URL from the previous step in the dialog that appears and click the "Connect" button. After this, you should now be connected to your local runtime.
Note: If you're using Mozilla Firefox, you'll need to set the
network.websocket.allowInsecureFromHTTPS preference within the Firefox config editor. Colab makes a connection to your local kernel using a WebSocket. By default, Firefox disallows connections from HTTPS domains using standard WebSockets.
If you share your notebook with others, the runtime on your local machine will not be shared. When others open the shared notebook, they will be connected to a standard Colab hosted runtime by default.
By default, all code cell outputs are stored in Google Drive. If your local connection will access sensitive data and you would like to omit code cell outputs, select Edit > Notebook settings > Omit code cell output when saving this notebook.
Connecting to a runtime on another machine
If the runtime you'd like to connect to is running on another machine (e.g. Google Compute Engine instance), you can set up SSH local port forwarding to allow Colab to connect to it.
First, set up your runtime using the instructions above.
Second, establish an SSH connection from your local machine to the remote instance (e.g. Google Compute Engine instance) and specify the '-L' flag. For example, to forward port 8888 on your local machine to port 8888 on your Google Compute Engine instance, run the following:
gcloud compute ssh --zone YOUR_ZONE YOUR_INSTANCE_NAME -- -L 8888:localhost:8888
Finally, make the connection within Colab by connecting to the forwarded port (follow the same instructions under Step 2: Connect to the local runtime).