# How to run Jupyter in the cloud Start JupyterLab on a cloud machine, upload your data next to it, and open it in your browser over HTTPS. 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](/docs/notebooks)). ## Run it on your own VM If you run Jupyter yourself, these are the parts that matter: ```bash no-run python3 -m pip install jupyterlab jupyter lab --no-browser --ip 127.0.0.1 --port 8888 ``` - **Keep it off the open internet.** Bind to `127.0.0.1` and 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](/how-to/call-the-rest-api-with-curl)). ```bash no-run API=https://api.withruntime.com AUTH="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.csv curl -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](/docs/reference/previews#previewcreate)). ## Run a cell without opening the browser Code can run cells in the same kernel a person would use. [`runCode`](/docs/reference/notebooks#runcode) sends one cell and returns what it printed, its value and any exception: ```bash no-run curl -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?](/glossary/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: ```bash no-run curl -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 .exitCode ``` ## Stop paying for it Delete the notebook when you are done. Its files go with it, so download anything you want to keep first. ```bash no-run curl -s -X DELETE "$API/v2/notebooks/${id}" -H "$AUTH" | jq .state # "deleted" ``` ## Related - [What is a Jupyter kernel?](/glossary/jupyter-kernel) - [How to set up a cloud development environment](/how-to/set-up-a-cloud-dev-environment) - [How to open VS Code in the browser](/how-to/open-vs-code-in-the-browser) - [How to run Jupyter notebooks headless in the cloud](/use-cases/notebook-execution) - [What is a preview URL?](/glossary/preview-url) Facts on this page were checked on 17 November 2026.