# Connect from VS Code or another IDE (/notebooks/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`.

<Callout title="Prerequisite">
  You need the `can_use_notebooks` permission. See [notebook sessions](/notebooks/sessions).
</Callout>

## Get your server URL and a token

Every editor needs the same two things.

<Steps>

<Step>
### Copy your server URL

Open **Notebooks** in its own browser tab. The address bar shows your notebook server URL, of the
form:

```text
https://jupyter.<your-databaas-domain>/user/<username>/
```

Copy it up to and including `/user/<username>/`.
</Step>

<Step>
### 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.
</Step>

</Steps>

Some editors want the token as part of the URL. Add it as a query parameter:

```text
https://jupyter.<your-databaas-domain>/user/<username>/?token=<token>
```

<Callout type="warn">
  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**.
</Callout>

## VS Code

1. Install the **JupyterHub** extension (`ms-toolsai.jupyter-hub`).
2. Create a notebook: open the command palette (**Ctrl+Shift+P**, or **Cmd+Shift+P** on macOS) and
   run **Create: New Jupyter Notebook**.
3. Select **Select Kernel** in the top right, then **Existing JupyterHub Server...**.
4. 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](/notebooks/querying-data)
works unchanged:

```python title="Read a table from your editor"
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](/notebooks/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.