Using an External Jupyter Server

How to connect InkRider to your own Jupyter Server for full Python environment control.

By default InkRider runs code in a browser-based Python environment (JupyterLite). This covers the core workflow for most users and requires no server setup.

If you need access to system libraries, local files, network calls, or a specific Python environment that you manage yourself, you can connect InkRider to an external Jupyter Server running on your machine or a server you control.

This is a Professional plan feature.

When To Use an External Server

Prefer an external server when you need:

Python packages that are not available in the local in-browser runtime (NumPy with C extensions, Pandas with full IO support, database drivers, etc.)
access to local files on your machine or a shared network drive
outbound HTTP requests from code cells
a reproducible environment you manage with conda, pip, or a container

JupyterLite is sufficient for most document-generation and calculation workflows and requires no server configuration.

Before You Start

Your machine must have Python and Jupyter Server installed.
You need an active Professional subscription for this feature.
The server and the Word add-in must be reachable from each other's network.

Install Jupyter Server if you do not already have it:

pip install jupyter_server

Starting the Server

Run the following in a terminal on the machine that will execute your code:

jupyter server --no-browser

On first run Jupyter prints a startup message that contains the server URL and a token:

[JupyterServerApp] Serving notebooks from local directory: /Users/you
[JupyterServerApp] Jupyter Server 2.x is running at:
[JupyterServerApp] http://localhost:8888/
[JupyterServerApp] Use Control-C to stop this server

Note the URL (http://localhost:8888) and the token (a long hex string that appears after ?token= in the full URL printed below). You will need both.

If you want a persistent token you can set one explicitly:

jupyter server --no-browser --ServerApp.token=your-token-here

Entering the URL and Token in InkRider

Open the InkRider add-in in Word.
Open Application Settings (gear icon in the header).
Switch to the Runtime tab.
Under Jupyter Server, enter the Base URL (http://localhost:8888).
Enter the Token from the startup message.
Click Test connection to confirm InkRider can reach the server.
Close the settings dialog.

The connection test pings the server's /api endpoint and reports the Jupyter Server version if it succeeds. A 403 response means the token is wrong.

Checking Connection Status

The globe or plug icon in the add-in header reflects the connection state:

Green outline: InkRider has an active connection to the server.
Default: no server URL is configured.
Click the icon to open the runtime panel, which shows the server URL and a Test connection button you can use at any time.

Switching Back to JupyterLite

Clear the Base URL field in Application Settings → Runtime and reload the add-in. InkRider will resume using JupyterLite as the local runtime.

Security Notes

Use HTTPS on any non-localhost server. When the server is accessible over a network, plain HTTP (http://) sends the authentication token unencrypted. InkRider warns you when this is the case. Set up TLS on your server or use an SSH tunnel:

ssh -L 8888:localhost:8888 user@remote-host

Then connect to http://localhost:8888; the SSH tunnel handles encryption.

Do not expose your Jupyter Server to the public internet without authentication. Use a strong token and restrict access with a firewall or VPN where practical.

Troubleshooting

Test connection times out (8 seconds)

Confirm the server is running: jupyter server list
Check that the URL matches exactly (protocol + host + port + no trailing /api, because InkRider appends that itself)
If the server is on a remote host, verify that port 8888 (or your custom port) is open

HTTP 403 (forbidden)

The token is incorrect. Copy it again from the Jupyter startup output.
If you started the server without a token intentionally, leave the token field empty.

Packages are missing

Confirm you are running jupyter server inside the correct conda environment or virtualenv.
After installing a package, restart the server.

CORS error in browser console

Jupyter Server allows cross-origin requests from the same origin by default. InkRider runs in a Word add-in iframe with a different origin. Start the server with the add-in's allowed origin:
```
jupyter server --ServerApp.allow_origin='*'
```
On a private local server this is acceptable. On a networked server, restrict to the specific origin.

Connection works but code does not run

Check the runtime dropdown in the header is set to Jupyter Server.
If you recently changed the token, update it in Application Settings and run Test connection again.

Documentation