Open JupyterLab
The Open button
Deploy a template whose launch mode is jupyter, wait for the instance to reach running, then open it from Instances. On the Connect tab there is an Open JupyterLab button. It takes you straight into an authenticated session in a new tab.
The button is the supported way in. Do not try to assemble the address yourself, and do not rely on a bookmark: the host and port an instance is published on can change after a stop and start, and the bookmark then points at nothing.
If the button is missing, check the launch mode of the template you deployed. Only jupyter starts a notebook server. An ssh-mode instance gives you a shell, not a notebook. See Launch modes.
Which address the button opens
The address the button opens depends on whether the host can be reached directly from outside:
| Route | Address | When | Certificate |
|---|---|---|---|
| Direct | https://<IP>:<port>/lab?token=… | The host's published ports can be reached directly from outside | One the container generates for itself; the browser warns (see The certificate warning) |
| Relay | https://<workload-id>-<jupyter-port>.relay.superheat.cloud/lab?token=… (8080 by default) | The host is behind NAT and cannot be reached directly | A publicly issued certificate; the browser does not warn |
When the instance reaches running, the platform checks once whether the host can be reached directly from outside. If it can, the button uses the direct address; if it cannot, the button goes through the relay. The relay is switched on only once Superheat CN moves to its superheat.cloud domain; until then the button always opens the direct address.
Both routes reach the same JupyterLab with the same token. SSH does not go through the relay; it always connects directly. See Connect over SSH.
About the token
The access token is minted by the platform when the instance is deployed and passed down to the container, which starts JupyterLab with that token as the only credential. You never choose it. Your organization can read it: the instance's Connect tab shows it under Access token, and the API returns it as access_token. It is the same token that guards the template's other app ports — see The instance access token.
Two things follow from that:
- Open JupyterLab from the console. The button carries the token for you, so you do not have to assemble the address. Treat the token, and the button's link, like a password.
- Setting
JUPYTER_TOKENyourself in the environment does nothing. The platform's environment overlay always wins over renter-supplied values, so your entry is overwritten. The same applies toGPU_COUNT. See Environment variables.
Where your files are
JupyterLab is rooted at JUPYTER_DIR, which defaults to /workspace. The file browser cannot navigate above that directory, so anything you want to see in the sidebar belongs under it.
| Setting | Default | Where it comes from |
|---|---|---|
JUPYTER_DIR | /workspace | the template's jupyter_dir field |
JUPYTER_PORT | 8080 | the container port jupyter mode publishes |
JUPYTER_LAB | true (Lab) | the template's use_jupyter_lab field; false serves the classic notebook |
/workspace is on the disk you sized at deploy, so it survives a stop and start and is deleted by a destroy. Files written elsewhere in the container are on the same disk and share the same fate — the directory is a convention, not a separate volume.
The tab opened before the server was ready
The Open JupyterLab button appears as soon as the instance reports running. The notebook server binds its port a moment after that, so an early click can land on a browser error — a refused connection, or a page that never finishes loading.
Wait a few seconds and reload the tab. The base image starts JupyterLab before it runs the template's onstart script, so a long onstart is not what is holding the notebook server up. If reloading still fails, read the server's own log over SSH:
tail -f /var/log/superheat/jupyter.log
The certificate warning
This section applies to the direct address only. On the direct route, JupyterLab is served over HTTPS using a certificate the container generates for itself, so your browser warns that it cannot verify the site. That warning is expected on a fresh instance. The encryption is doing its job; only the identity is unverifiable, because no public authority has signed a certificate for a machine that came into existence minutes ago.
The relay address uses a certificate publicly issued for *.relay.superheat.cloud, so the browser does not warn.