# Connecting a notebook to your cluster

Connect a notebook to an Eugo cluster with the EugoHPC Manager, check that it is connected, disconnect, and run your own Python scripts on the cluster.

Source: https://docs.eugo.io/docs/guides/connecting-a-notebook/

---

Code you write with `eugo.hpc` runs wherever your notebook is connected. You mark a function with `@eugo.hpc.distribute`, start it with `.remote(...)`, and collect its result with `eugo.hpc.get(...)`. Once the notebook is connected to a cluster, those tasks run on the cluster's nodes.

This page covers the everyday route: connect with the **Connect** button in the EugoHPC Manager, check the connection, run work, and disconnect. For launching, scaling and terminating clusters, and for writing a connection by hand, see [EugoHPC Manager](./hpc-cluster-manager.md).

> **Note:** `eugo.hpc` code also runs when the notebook is not connected, but not on your cluster. Without a connection, your first `.remote(...)` call, or a call to `eugo.hpc.init()` with no address, starts a small private Ray inside your own session, and the log line reads `Started a local Ray instance.` Your tasks then run on your session's own CPUs. Connect first when you want the cluster.

> **Note:** The outputs on this page were captured in an Eugo lab session with no cluster connected. Steps that need your cluster are shown without output. Version strings (Python `3.14.6`, Ray `3.0.0.dev0`) change from one image to the next, and long log output is trimmed and marked with `…`.

## Before you start

You need two things:

1. **A running cluster.** Launch one from the EugoHPC Manager and wait until it has finished starting. While it is still starting, its Connect button is greyed out, with the tooltip "Connect unavailable while provisioning". See [Cluster lifecycle](./hpc-cluster-manager.md#cluster-lifecycle).
2. **An open notebook.** Connect works on the notebook you have open. With no notebook open, it stops and asks you to open a notebook first.

## Connect with the Connect button

1. Open the notebook you want to work in, and click the cell you want the connection to go below.
2. In the EugoHPC Manager, find the cluster and click its **Connect** button (a play icon; its tooltip reads "Connect cluster").

Connect then does three things in your notebook:

1. **It gives this notebook's kernel the cluster's access token**, out of sight. No screen shows the token; see "About the token" in [Connecting by hand](./hpc-cluster-manager.md#connecting-by-hand).
2. **It adds a cell below the one you clicked, and runs it.** The cell holds your cluster's address, filled in for you:

   ```python
   import eugo.hpc
   eugo.hpc.init(address="ray://<head>:10001");
   ```

   The semicolon at the end only stops the notebook from printing the object `init` returns.
3. **It checks that the kernel really is connected.** If any step fails, the EugoHPC Manager reports `Failed to connect to cluster:` followed by the reason.

When Connect has finished, the cluster's card shows **Disconnect** where Connect was, and **Open Dashboard**, which opens the cluster's Ray dashboard (shown when the cluster reports its dashboard address).

Now run something on the cluster:

```python
import eugo.hpc

@eugo.hpc.distribute
def square(x):
    return x * x

eugo.hpc.get([square.remote(i) for i in range(4)])
```

Call the function with `.remote(...)` and collect the result with `eugo.hpc.get(...)`. Calling it directly, as `square(3)`, raises `TypeError: Remote functions cannot be called directly.`

### Things to know about Connect

1. **The connection belongs to this notebook's kernel.** Your other notebooks are not connected. Neither is this one after you restart its kernel: after a restart, the card offers Connect again, so click it. The notebook still remembers which cluster it used, and the card also shows a small "Disconnect: forget this notebook's saved connection" button. That button only drops the saved choice; nothing runs in the kernel.
2. **Do not re-run the old connection cell.** The cell Connect added stays in your notebook. Running it again while the kernel is connected fails, because Ray is already connected: `RuntimeError: Ray Client is already connected.` Running it in a restarted kernel also fails, because that kernel does not have the cluster's token. Usually it fails at once: `AuthenticationError: Token authentication is enabled but Ray couldn't find an authentication token.` If a private Ray (the one in the note at the top of this page) ran earlier in your session, the kernel finds that Ray's own token instead, the cluster refuses it, and after about 30 seconds the cell fails with `ConnectionError: ray client connection timeout`. Either way, click Connect instead; it adds a fresh cell.
3. **Switching to another cluster.** If the notebook is connected to one cluster and you click Connect on another, the EugoHPC Manager asks first, in a dialog titled "Switch Cluster Connection". Continuing shuts down the current connection in this notebook, stops any in-flight jobs tied to it, and connects the notebook to the other cluster; only this notebook is affected. Choose **Disconnect and Connect** to switch, or **Cancel**. Collect the results you need first.
4. **If the notebook already runs a Ray of its own.** If cluster code ran in the notebook before you clicked Connect (a `.remote(...)` call, or `eugo.hpc.init()`), the kernel already runs the private Ray from the note at the top of this page. Connect does not connect over it. Instead, the cards offer **Disconnect** in Connect's place, with the tooltip "This notebook is already running Ray, started by a cell rather than through Connect. Disconnect it before connecting a cluster." The cards show the same Disconnect and tooltip when you connected the notebook to a cluster yourself, with `eugo.hpc.init(address=...)` in a cell, as in [Connect with your own settings](#connect-with-your-own-settings). For the private Ray, click that Disconnect to stop it, then click Connect. For a connection you made yourself, leave it: clicking Disconnect ends it.

## Check that you are connected

```python
import eugo.hpc

eugo.hpc.is_initialized()
```

This returns `True` once Connect has finished; Connect runs the same check itself before it reports success. It returns `False` in a kernel that has not connected, and again after you disconnect. In a new kernel, before Connect, it prints:

```text
False
```

`True` alone does not prove you are on the cluster: it is also `True` while the private Ray from the note at the top of this page is running. Here is that case, in a kernel with no connection. A call to `eugo.hpc.init()` with no address starts the private Ray:

```python
eugo.hpc.init()
```

```text
…
2026-11-14 05:58:46,716	INFO worker.py:2015 -- Started a local Ray instance. View the dashboard at http://127.0.0.1:8265
RayContext(dashboard_url='127.0.0.1:8265', python_version='3.14.6', ray_version='3.0.0.dev0', ray_commit='…')
```

and the check then returns `True`, although nothing is connected to your cluster:

```python
eugo.hpc.is_initialized()
```

```text
True
```

To see where your tasks will run, ask for the resources:

```python
eugo.hpc.cluster_resources()
```

On the cluster, this lists the CPUs, memory and GPUs of all the cluster's nodes together. In a private Ray it lists only your own session's. `eugo.hpc.nodes()` lists the nodes themselves.

## Disconnect

Click **Disconnect** on the cluster's card. Disconnect adds a cell below the selected one and runs it:

```python
import eugo.hpc
if eugo.hpc.is_initialized():
    eugo.hpc.shutdown()
```

It then checks that the connection has ended. Collect the results you still need with `eugo.hpc.get(...)` before you disconnect: disconnecting stops the jobs still running for this notebook.

After you disconnect, `eugo.hpc.is_initialized()` returns `False`, and the next `.remote(...)` call starts a private Ray in your session again, as in the note at the top of this page. Click Connect when you want the cluster back.

## Connect with your own settings

The Connect button makes a plain connection. To give the whole connection a runtime environment (environment variables, extra packages, your own code), let Connect set it up first, then replace it with your own:

1. Click **Connect**, so the kernel gets the cluster's token. Copy the `ray://` address from the cell Connect added.
2. Click **Disconnect**, in the same notebook. While Connect's connection is active, a second `eugo.hpc.init(address=...)` fails.
3. In the same kernel, connect with your settings:

   ```python
   import eugo.hpc

   eugo.hpc.init(
       address="ray://<head>:10001",
       runtime_env={"env_vars": {"MY_FLAG": "1"}},
   )
   ```

   Replace `ray://<head>:10001` with the address you copied.

The cards do not show a connection you make this way as connected. Right after your `init`, the card still shows Connect. When you next open or switch to this notebook, or click Connect, the cards show **Disconnect** in Connect's place instead, with the started-by-a-cell tooltip from item 4 of [Things to know about Connect](#things-to-know-about-connect). That is your own connection: leave it while you work. Clicking that Disconnect ends it.

Stay in the same kernel throughout: the token Connect gave it stays there after you disconnect, while a restarted kernel or another notebook has none. The steps in full, the token, and every `runtime_env` key are in [Connecting by hand](./hpc-cluster-manager.md#connecting-by-hand); what each key installs or ships is in [Installing Python packages](./installing-python-packages.md#packages-on-the-cluster). To change the settings for one task only, use `@eugo.hpc.distribute(runtime_env=...)` instead.

## Run a Python script on the cluster

A script reaches the cluster through the notebook's connection. Write it so that it connects only when nothing is connected yet:

```python
import eugo.hpc

if not eugo.hpc.is_initialized():
    eugo.hpc.init()

@eugo.hpc.distribute
def square(x):
    return x * x

print(eugo.hpc.get([square.remote(i) for i in range(4)]))
```

Save it as `my_script.py` next to your notebook, then run it from the connected notebook:

```python
%run my_script.py
```

`%run` runs the script inside the notebook's kernel. The kernel is already connected, so `eugo.hpc.is_initialized()` is `True`, the script skips its own `init()`, and its tasks run on the cluster.

Run on its own instead, for example in a terminal, the script is not connected to anything: its `eugo.hpc.init()` starts a private Ray in your session, and the tasks run there:

```text
$ python3 my_script.py
…
2026-11-14 05:59:19,883	INFO worker.py:2015 -- Started a local Ray instance. View the dashboard at http://127.0.0.1:8265
[0, 1, 4, 9]
…
```

The answer is the same, but it was computed on your session's own CPUs, not on the cluster. Only the kernel you clicked Connect in holds the cluster's token, so to run a script on the cluster, run it from that notebook with `%run`.

## Related pages

- [EugoHPC Manager](./hpc-cluster-manager.md): launching, scaling and terminating clusters, and connecting by hand.
- [Installing Python packages](./installing-python-packages.md): packages and your own code on the cluster's workers.
- [EugoIDE](../platform/ide.md): the browser-based development environment your notebooks run in.
