Connect from VS Code or another IDE
Run notebooks from your local editor against your Databaas notebook server.
You do not have to work in the browser. An editor that can attach to a JupyterHub server gives you
your own editor and shortcuts, while the code runs on your Databaas notebook server — with your
permissions, your files and databaas-utils.
Prerequisite
You need the can_use_notebooks permission. See notebook sessions.
Get your server URL and a token
Every editor needs the same two things.
Copy your server URL
Open Notebooks in its own browser tab. The address bar shows your notebook server URL, of the form:
https://jupyter.<your-databaas-domain>/user/<username>/Copy it up to and including /user/<username>/.
Create a token
In JupyterLab, open File → Hub Control Panel, select Token, and request a new token. Copy it when it is shown. It stays valid until you revoke it, so it survives restarts of your server.
Some editors want the token as part of the URL. Add it as a query parameter:
https://jupyter.<your-databaas-domain>/user/<username>/?token=<token>Treat the token like a password: anyone with it can run code on your server as you, with your data access. Do not paste it into shared channels, commits or notebooks. If it leaks, revoke it in File → Hub Control Panel → Token.
VS Code
- Install the JupyterHub extension (
ms-toolsai.jupyter-hub). - Create a notebook: open the command palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS) and run Create: New Jupyter Notebook.
- Select Select Kernel in the top right, then Existing JupyterHub Server….
- Paste your URL with the token, name the connection, and pick a kernel.
The same steps work in editors built on VS Code that ship this extension, such as Cursor and Windsurf.
PyCharm
In PyCharm Professional, open Tools → Add Jupyter Connection, add an external server, paste your server URL, and supply the token. Use Test connection before you save.
JupyterLab Desktop
On the Welcome page, choose Connect… and paste your URL with the token. JupyterLab Desktop
reads the token from the ?token= part.
Other editors
Any client that can attach to an existing JupyterHub or Jupyter server works with the same URL and token. An option that connects to a running kernel through a local connection file is a different mechanism and does not reach a remote server; look for the one that asks for a server URL.
Use the catalog
The kernel runs on your notebook server, so everything in querying data works unchanged:
from databaas_utils.notebook import get_catalog
catalog = get_catalog()
catalog.load_table("<namespace>.<table>").scan(limit=10).to_pandas()Limitations
- Your files live on Databaas, not on your laptop. The editor is local; the kernel, the filesystem and the data access are remote. A notebook you open from your laptop runs on the server, but reads and writes files on the server, not next to the notebook on your disk. See notebook storage.
- marimo notebooks cannot use the remote server. The marimo editor extension does not connect to an external server; open marimo notebooks in the browser.
- Zed is not supported. Its REPL runs against local kernels only.
- If the connection fails, start your server first. Open Notebooks in the browser, wait for JupyterLab to load, then reconnect.