How to use dot with Google Colab — setup and first notebook

From private deployment and Google authorization to a finished analysis your dot can deliver.

By KaiQin04 · Updated · v0.3.5

Before you start: accounts and expected results

You will ask your dot to create one CPU notebook, analyze 100 synthetic sales records, retrieve two CSV files, a chart, and an executed .ipynb, then release the task runtime. If you already have a private deployment, start at step 3.

  • An account with access to dot, private ChatGPT Sites, and the Sites plugin. Availability varies by account.
  • Your own Google Colab account, Google Cloud project, and OAuth Web client.
  • For initial deployment, an environment with Node.js 22.13+, npm, and uv/Python 3.12. An agent with Sites tools can help.

The exercise uses entirely synthetic data and requires no personal file uploads. Execution uses your own Colab account, subject to its resources and compute-credit rules.

1. Create your private backend

GitHub Pages hosts the documentation you are reading. The notebook backend runs in a separately deployed ChatGPT Site accessible only to you.

Give this request to an agent with Sites tools:

Read https://github.com/KaiQin04/chatgpt-colab-plugin, its AGENTS.md, docs/DEPLOYMENT.en.md, docs/OAUTH.en.md, and skills/setup/SKILL.md. Use the current installed Sites skill to deploy the v0.3.5 source to a new Site that only I can access, with my own Google OAuth client. Help me connect its private plugin. I will enter credentials in the settings UI and authorize Google in my browser. Start with checks that do not allocate a Colab runtime; do not change any existing Site.

This guide uses v0.3.5 as an example. To obtain the source yourself, use these commands:

git clone https://github.com/KaiQin04/chatgpt-colab-plugin.git
cd chatgpt-colab-plugin
git switch --detach v0.3.5

The agent should create a new Site from this template, apply database migrations, configure the actual deployment identifiers, and confirm that you are its owner and sole viewer. Set OWNER_PRIVATE_DEPLOYMENT_CONFIRMED=true only after verifying owner-only access. Follow the deployment guide for exact commands, bindings, and build steps.

If your account cannot create a private Site, resolve Sites access first.

2. Configure Google OAuth and authorize

  1. Open Google Auth Platform in your own Google Cloud project. Configure Branding and Audience. For personal testing, choose External / Testing and add your Google account as a test user.
  2. Follow the OAuth guide to configure openid, https://www.googleapis.com/auth/userinfo.email, and https://www.googleapis.com/auth/colaboratory.
  3. Create a Web application client and add the exact redirect URI printed by the deployment configuration script. Its path is /oauth/google/callback on your own Site domain.
  4. Enter GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and TOKEN_ENCRYPTION_KEY in your Site settings. Generate the encryption key in your own terminal as described in the deployment guide and enter it directly in the secrets interface.
  5. After private deployment, open the Site as its owner, follow its Google authorization link, and review the application name, account, and scopes in your browser before consenting.

Keep client secrets, tokens, and encryption keys out of chat and Git. Complete Google sign-in yourself. Testing-mode refresh tokens may require periodic reauthorization; see the OAuth guide for the conditions and production requirements.

3. Connect the plugin and check your dot’s tools

Install or connect the private plugin created for this Site. If you cannot find it, ask an agent with Sites tools to read get_site(include_mcp_connection: true) and show the connection UI using the returned plugin ID.

OpenAI documents that dots can use existing plugin connections within granted permissions. Confirm that this particular dot has access to your plugin’s tools. See the official permissions guide.

Check whether my connected Colab plugin exposes its notebook tools. Read runtime package settings, compute status, and existing notebooks. Do not allocate a runtime, install packages, or execute code yet. Report connection status, eligible machines, and any existing tasks with unreleased runtimes.

The relevant tools are get_runtime_settings and get_compute_status. If tools are missing, resolve the plugin connection, Google authorization, or permissions first.

4. Ask your dot to run the first analysis

Use my Colab plugin to create a CPU notebook. Generate 100 synthetic sales records with a fixed random seed, summarize revenue by product, and draw a bar chart. Save sales.csv, summary.csv, and revenue.png in outputs, export the notebook for me, and release this task’s runtime when finished.

Ask your dot to retain the code and results in the notebook. Use columns named product, quantity, unit_price, and revenue, with synthetic product categories A, B, and C. It should check the required packages and prepare them in this runtime if needed.

Add these reproducibility and validation requirements:

Use random seed 42. Calculate revenue = quantity × unit_price for each record and sum revenue by product. Check that product totals equal the original total revenue, that there are 100 records, and that no values are missing. Use English chart labels.

Your dot should create the notebook, save cells, submit execution, and poll the result. You can also edit a cell and press Shift + Enter in the editor.

5. Verify and download the results

After execution completes, ask your dot to confirm that outputs are saved, export the notebook, and provide usable downloads.

Table 1. Expected output files
FileAcceptance check
sales.csv100 synthetic records with the requested columns and types.
summary.csvRevenue per product; its total equals total revenue in the source data.
revenue.pngOpens successfully, has readable labels, and agrees with summary.csv.
*.ipynbOpens in a notebook tool and contains the code, random seed, and corresponding execution outputs.

Write generated files into the notebook workspace’s outputs/ directory so the plugin can save them as artifacts. The workflow uses get_notebook, get_artifacts, and export_ipynb. Open the downloaded files to check them.

6. Release this task’s runtime and confirm

After saving and downloading the results, ask your dot to call close_notebook for this notebook, then read back compute status to confirm its runtime was released.

Once all the files have been retrieved, release this task’s runtime.

Keep the runtime open until your files are saved.

Troubleshooting

Your dot cannot find the Colab tools
Check that the private plugin is connected and this dot has tool access. Complete the connection before requesting execution.
Google reports redirect_uri_mismatch
Compare the OAuth Web client’s redirect URI with the full value printed by the configuration script, including scheme, domain, and callback path.
Authorization expires or is revoked
Reauthorize through your private Site and check the OAuth guide’s Testing-mode explanation. Do not manually copy refresh tokens.
Allocation returns HTTP 503
If an allocation POST returns HTTP 503 before a runtime endpoint is captured, the notebook attempt is closed. To start again, use a new idempotencyKey. Reusing the same key returns the original result. The failed request is counted separately from running or unresolved runtimes. Its diagnostic record is retained, and closing the attempt does not confirm that Google released a runtime.
Execution times out or its outcome is unknown
You can check the original notebook's status or open a new notebook to keep working. The new notebook is allocated independently and does not automatically stop the original runtime.
A download fails or an artifact is missing
Check that the file is in the workspace outputs directory, execution is complete, and the artifact is saved. Resolve persistence while the runtime is still available, then request a fresh download link.

After verifying this CPU workflow, expand to your own data or GPU workloads. Ask your dot to check current hardware and workload requirements before allocating a GPU. De-identify personally identifiable data before uploading it.

References

Report a documentation or setup issue →