That is the whole job. The rest is choosing where the machine runs, how the browser reaches it safely, and what happens to your kernels when you stop working. Three common ways to do it:
| Way | What you manage | Good for |
|---|---|---|
A VM you run jupyter lab on |
The OS, Python, TLS, a login token, a firewall, and stopping it at night | Full control, long-lived servers |
| A hosted notebook service | Little; the service picks the machine and the packages | Quick, shared, browser-only work |
| A notebook machine started by an API | The data and the code; the machine is made and paused for you | Notebooks your own code creates |
On Runtime, a notebook is a Linux machine with JupyterLab, NumPy and
pandas already running on port 8888 over /workspace. You reach it
through a private HTTPS preview, and after 300 seconds with nothing
happening it pauses with its kernels kept in memory. The next visit or call
resumes it where it was (Notebooks).
Run it on your own VM
If you run Jupyter yourself, these are the parts that matter:
Terminalpython3 -m pip install jupyterlabjupyter lab --no-browser --ip 127.0.0.1 --port 8888- Keep it off the open internet. Bind to
127.0.0.1and reach it through an SSH tunnel (ssh -L 8888:localhost:8888 you@host), or put it behind a proxy that terminates TLS and checks a login. A Jupyter server runs any code its visitors send. - Keep the token. Jupyter prints a URL with
?token=. Anyone with that URL can run code as the server's user. - Decide what happens overnight. A stopped VM loses every running kernel and its variables. A running VM keeps billing.
Run it on Runtime with the REST API
This script creates a notebook, uploads a CSV into /workspace, and prints a
link that opens JupyterLab in a browser. It needs curl, jq and an API key
in RUNTIME_API_KEY (call the API with curl).
TerminalAPI=https://api.withruntime.comAUTH="Authorization: Bearer $RUNTIME_API_KEY"# 1. Create a notebook: JupyterLab on port 8888 over /workspace.id=$(curl -sf -X POST "$API/v2/notebooks" -H "$AUTH" \ -H "Content-Type: application/json" -d '{}' | jq -r .id)# 2. Upload a data file into /workspace.printf 'region,sales\nnorth,125\nsouth,250\nwest,375\n' > sales.csvcurl -sf -X PUT "$API/v2/notebooks/${id}/files?path=/workspace/sales.csv" -H "$AUTH" \ -H "Content-Type: application/octet-stream" --data-binary @sales.csv > /dev/null# 3. Share port 8888 with a private preview and print the address to open.preview=$(curl -sf -X POST "$API/v2/sandboxes/${id}/previews" -H "$AUTH" \ -H "Content-Type: application/json" -d '{"port": 8888}')echo "$(echo "$preview" | jq -r .url)lab?runtime_preview_token=$(echo "$preview" | jq -r .token)"Open the printed link. JupyterLab shows sales.csv in its file browser. The
preview is private: without its token the address answers 401. The token
lasts up to a day unless you ask for another lifetime with ttlSeconds
(previews).
Run a cell without opening the browser
Code can run cells in the same kernel a person would use.
runCode sends one cell and returns what
it printed, its value and any exception:
Terminalcurl -s -X POST "$API/v2/notebooks/${id}:runCode" -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{"code": "import pandas as pd\ndf = pd.read_csv(\"/workspace/sales.csv\")\ndf[\"sales\"].sum()"}' \ | jq -c '{status, value: .results[0].text}'# {"status":"ok","value":"750"}Variables stay for the next cell, including across a pause
(what is a Jupyter kernel?). An agent connected to
Runtime's MCP server does the same with runtime_notebooks_run_code.
Run a whole notebook file
To run an .ipynb from top to bottom, as a scheduled report does, call
nbconvert on the machine. The outputs are saved into the file:
Terminalcurl -s -X POST "$API/v2/notebooks/${id}:exec" -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{"cmd": "cd /workspace && jupyter nbconvert --to notebook --execute --inplace report.ipynb"}' \ | jq .exitCodeStop paying for it
Delete the notebook when you are done. Its files go with it, so download anything you want to keep first.
Terminalcurl -s -X DELETE "$API/v2/notebooks/${id}" -H "$AUTH" | jq .state# "deleted"Related
- What is a Jupyter kernel?
- How to set up a cloud development environment
- How to open VS Code in the browser
- How to run Jupyter notebooks headless in the cloud
- What is a preview URL?
Facts on this page were checked on 17 November 2026.