Skip to main content
← All guides

Share a Jupyter notebook remotely

Why qURL here

Work with someone in the Jupyter notebook running on your machine, with nothing to deploy. Keep Jupyter’s token or password and allow only the exact origin of the recipient’s open qURL™ link.

Steps

To share a Jupyter notebook remotely with qURL by LayerV, start JupyterLab on 127.0.0.1 with ServerApp.allow_remote_access enabled and its token kept. Publish port 8888 with qurl publish and send a qurl share link. After the collaborator opens it, restart with their exact https origin in ServerApp.allow_origin and send the new token separately. The collaborator uses the notebook running on your own machine through qURL.

  1. Install the qURL CLI

    Install the qURL CLI. On macOS, install it with Homebrew. On Linux and Windows, download the package for your platform from the latest release; the CLI page lists each one. Nothing asks you to sign up.

    brew install layervai/tap/qurl
    qurl --version
  2. JupyterLab remote access: start on localhost

    Jupyter answers 403 to any request whose Host header is not a local name, and through qURL the Host is c-….qurl.site. ServerApp.allow_remote_access turns that check off; the server still listens on 127.0.0.1 only. Keep the token Jupyter generates: every request still needs it. Never start Jupyter with an empty token. If port 8888 is taken, Jupyter moves to the next free port; use the port in the URL it prints. Keep it running, and use a second terminal for the qurl commands.

    jupyter lab --ip=127.0.0.1 --port=8888 --no-browser \
      --ServerApp.allow_remote_access=True
  3. Publish Jupyter

    Publish the app through qURL. The first publish creates this device’s identity, starts a background service that keeps serving after you close the terminal (while you stay logged in), and prints the app’s CRID, its stable ID. The Access row says who can open the app: a plain publish makes it private from qurl 3.4.1 on. qurl share turns the CRID into an access link, and the link is what you send.

    qurl publish http://127.0.0.1:8888
  4. Trust the collaborator’s exact origin, then send the token

    Jupyter checks the Origin of logins, API writes and kernel WebSockets against the Host it receives. Through qURL the browser is on r_….qurl.site and Jupyter receives c-….qurl.site, so the login form and kernels fail until you name the origin. Ask the collaborator to send you the exact https origin from the address bar of the page they just opened (scheme and hostname, without a path, in lowercase). They must keep that page open; do not open their single-use link yourself. Stop Jupyter, start it again with ServerApp.allow_origin set to that origin, and ask them to reload the same page. A restart makes a new token: run jupyter server list and send them the token in a separate message. Do not use allow_origin=* or a pattern that matches every qurl.site origin: both trust apps run by other publishers.

    jupyter lab --ip=127.0.0.1 --port=8888 --no-browser \
      --ServerApp.allow_remote_access=True \
      --ServerApp.allow_origin=https://r_your-link.qurl.site
    jupyter server list   # prints the URL with ?token=…
  5. End the review and restore local settings

    Stop sharing, remove the recipient origin you added to ServerApp.allow_origin, then restart Jupyter with its token or password still enabled.

    qurl stop <CRID>

What the recipient sees

The collaborator reloads and sees Jupyter’s login page, “Password or token:”.

More

They paste the token and land in JupyterLab at an address like https://r_….qurl.site/lab, with your files, kernels and terminals. Kernels connect over WebSockets, which a qURL link carries. Code they run executes on your machine, as you.

Troubleshooting

Troubleshooting
If you seeDo this
403 Forbidden, and the Jupyter log says “Blocking request with non-local 'Host' c-….qurl.site”Start Jupyter with --ServerApp.allow_remote_access=True. ServerApp.local_hostnames takes exact names only, so it cannot cover c-….qurl.site hosts in general.
The token is rejected at login, or the kernel never connectsIf the Jupyter log says “Blocking Cross Origin API request” or “Blocking Cross Origin WebSocket Attempt”, set --ServerApp.allow_origin to the collaborator’s exact origin, in lowercase, and restart. The browser sends its origin in lowercase, and Jupyter compares the strings exactly.
Show 7 more fixes
More troubleshooting
If you seeDo this
The token you sent stopped workingJupyter generates a new token each time it starts. Run jupyter server list and send the current one, or set a password once with jupyter server password.
qurl publish says the local app is not accepting TCP connectionsStart the app first and check that curl works on the same address. qurl publish connects to localhost as 127.0.0.1, so if your app listens only on IPv6 (on macOS or Linux, lsof -iTCP -sTCP:LISTEN -nP shows [::1]), publish 'http://[::1]:PORT' instead, or start the dev server with --host 127.0.0.1 and publish that address. Neither requires listening on your LAN. Keep the quotes: zsh treats the brackets as a pattern.
The recipient sees “Access link invalid”The link was already used or has expired. Run qurl share again and send the new link.
The recipient sees “Resource not found”The resource was deleted after the link was made. Publish the app again, then run qurl share and send the new link.
publish rejects http://127.0.0.1 with “only HTTPS URLs are allowed”, asks you to log in, or prints no Access: lineYour qURL CLI is out of date. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release. After updating, qurl --version prints 3.4.1 or later, and every publish is private by default.
publish says this Linux session “can’t reach a systemd user manager”You are in a container or sandbox without a user service manager. Run qurl publish with --foreground; sharing lasts as long as that process runs. Container and CI setup →
publish says “Quota Exceeded” with “protected resource limit reached”, or “Your qURL account has reached a plan limit”You can see this without an account: a device with no account can keep up to 3 active resources, with links that last up to 24 hours. Run qurl list --status active, then qurl delete <CRID> for any you no longer need (it asks you to confirm; --yes skips that). qurl stop keeps the resource, so it does not free a slot.

Frequently Asked Questions

Why does Jupyter reject the request with a Host or Origin error?

Jupyter receives a c-….qurl.site Host while the browser uses an r_….qurl.site origin. Keep it on loopback, enable ServerApp.allow_remote_access, and set ServerApp.allow_origin to the collaborator’s exact lowercase https origin. Keep the token and restart Jupyter after changing the origin.

What can the other person do in my notebook?

JupyterLab gives the collaborator the files, kernels and terminals your server exposes. Code runs on your computer as your user. Share it only with someone you trust to use that environment, and keep Jupyter’s token or password enabled.

Is it safe to turn on allow_remote_access?

It turns off Jupyter’s Host check, which guards against DNS rebinding. Jupyter still listens on 127.0.0.1 only, and every request still needs the token. Jupyter’s security docs warn that access to the server means running arbitrary code, and call disabling authentication not recommended.

Does the Jupyter token still apply?

A qURL link is a bearer secret: whoever opens it first uses it. Browser access stays with that browser and does not replace Jupyter’s login. Exposed Jupyter servers are a known target: in 2023 the Qubitstrike campaign broke into publicly reachable Jupyter instances to mine cryptocurrency and steal cloud credentials. The token keeps code execution behind a secret.

Can two collaborators edit the same notebook at once?

jupyter-collaboration adds real-time editing to JupyterLab 4, and collaborators work in the same environment as you. Through qURL each one needs a link, and allow_origin takes one origin, so add people one at a time.

Who else can reach my app while the link is open?

Opening a qURL link starts a session for that browser, which lasts 1 hour by default. After a browser opens it, another browser on the same public IP cannot use its access. A script or agent that opens the link without a browser is admitted by its network address instead, which other devices on that public IP share until the session ends. A link admits whoever opens it: the API’s IP and country rules do not apply to the signed links qurl share issues. Keep your app’s own sign-in for anything sensitive.

Does my computer have to stay on?

Yes. Your Jupyter app runs on your machine. The machine and app must stay running and connected; the app is unavailable while the machine is asleep.

How do I stop sharing?

Run qurl stop <CRID> to pause serving the app, and qurl start <CRID> to resume it; a stopped app still counts toward your resource limit. qurl delete <CRID> removes the resource for good after asking you to confirm; its CRID can never be shared again.

Publish your app now

Install the CLI, then run one command. No sign-up, no API key.

Install the CLI →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.