Skip to main content

Releases

Migration Guide to 1.2.0​

Version 1.2.0 completes the terminology migration from runtime to code sandbox.

This is primarily a naming and configuration migration. Execution behavior is the same goal as before: notebooks are stored on a document server and code is executed by a kernel backend. The backend is now consistently called code sandbox across CLI, environment variables, config model, and docs.

Who Should Migrate​

  • End users running jupyter-mcp-server locally or in CI.
  • Operators maintaining shared MCP server deployments (containers, services, platform templates, runbooks).

Breaking Change Summary​

  • Use code_sandbox names everywhere instead of runtime names.
  • Use CODE_SANDBOX_* environment variables and matching CLI flags.
  • Use start_new_code_sandbox naming for bootstrap behavior.
  • Any custom scripts or wrappers using old runtime names must be updated.

Rename Matrix​

Old (pre-1.2.0)New (1.2.0+)
runtimecode sandbox
RUNTIME_URLCODE_SANDBOX_URL
RUNTIME_TOKENCODE_SANDBOX_TOKEN
RUNTIME_PASSWORDCODE_SANDBOX_PASSWORD
RUNTIME_IDCODE_SANDBOX_ID
START_NEW_RUNTIMESTART_NEW_CODE_SANDBOX
--runtime-url--code-sandbox-url
--runtime-token--code-sandbox-token
--runtime-password--code-sandbox-password
--runtime-id--code-sandbox-id
--start-new-runtime--start-new-code-sandbox

End User Migration​

1. Update environment variables​

Before:

export RUNTIME_URL=http://localhost:8888
export RUNTIME_TOKEN=MY_TOKEN
export START_NEW_RUNTIME=true

After:

export CODE_SANDBOX_URL=http://localhost:8888
export CODE_SANDBOX_TOKEN=MY_TOKEN
export START_NEW_CODE_SANDBOX=true

2. Update CLI commands​

Before:

jupyter-mcp-server \
	--runtime-url http://localhost:8888 \
	--runtime-token MY_TOKEN

After:

jupyter-mcp-server \
	--code-sandbox-url http://localhost:8888 \
	--code-sandbox-token MY_TOKEN

3. Validate split document + code sandbox setups​

If you run document storage and execution on different servers, ensure both sides are configured explicitly:

export DOCUMENT_URL=http://notebook-storage:8888
export DOCUMENT_TOKEN=DOC_TOKEN

export CODE_SANDBOX_URL=http://compute-cluster:8888
export CODE_SANDBOX_TOKEN=EXEC_TOKEN

4. Validate auth mode​

Token and password auth still work the same way, just with updated names:

  • CODE_SANDBOX_TOKEN or CODE_SANDBOX_PASSWORD
  • DOCUMENT_TOKEN or DOCUMENT_PASSWORD

When both token and password are supplied, password authentication takes precedence.

Operator Migration​

1. Update deployment manifests and templates​

Update references in:

  • Kubernetes manifests
  • Helm values/templates
  • Docker Compose files
  • systemd units
  • CI/CD secrets and variable groups

Recommended approach:

  1. Add new CODE_SANDBOX_* variables.
  2. Remove old RUNTIME_* variables.
  3. Restart workloads and verify MCP health checks.

2. Update startup wrappers and runbooks​

Search and replace in operational scripts:

  • runtime -> code_sandbox for internal names
  • runtime-oriented flags -> --code-sandbox-*

Also update on-call docs and incident runbooks so diagnostics use current naming.

3. Validate service behavior post-cutover​

Run these checks after rollout:

  1. MCP health endpoint returns healthy status.
  2. Kernel listing works (list_kernels).
  3. Notebook operations work (use_notebook, read_cell, execute_cell).
  4. Reconnect behavior remains as expected (RECONNECT_INTERVAL).

Configuration Examples (1.2.0+)​

Single Jupyter server for both document and code sandbox​

export JUPYTER_URL=http://localhost:8888
export JUPYTER_TOKEN=MY_TOKEN

Explicit dual-server topology​

export DOCUMENT_URL=http://notebook-storage:8888
export DOCUMENT_TOKEN=DOC_TOKEN
export DOCUMENT_ID=shared/analysis.ipynb

export CODE_SANDBOX_URL=http://compute-cluster:8888
export CODE_SANDBOX_TOKEN=EXEC_TOKEN
export START_NEW_CODE_SANDBOX=false

Sandbox variant execution​

export SANDBOX_VARIANT=kaggle
export CODE_SANDBOX_CHANNELS_URL=wss://.../api/kernels/.../channels?...
export SANDBOX_GPU=T4

Known Migration Pitfalls​

  • Old RUNTIME_* names left in environment but ignored by new startup paths.
  • Mixed old/new names across microservices causing partial misconfiguration.
  • Wrapper scripts updated, but CI secrets still use old key names.
  • Documentation drift in internal playbooks and customer onboarding docs.
  1. Replace all RUNTIME_* env vars with CODE_SANDBOX_*.
  2. Replace all runtime CLI flags with code sandbox flags.
  3. Update deployment manifests, secrets, and runbooks.
  4. Validate health plus core notebook execution flows.
  5. Remove old naming from internal docs to prevent regressions.

For full reference values, see Configuration.

Latest Release​

See the latest release notes on the GitHub Releases page.

Older Releases​

0.16.x - 13 Oct 2025​

0.15.x - 08 Oct 2025​

0.14.0 - 03 Oct 2025​

0.13.0 - 25 Sep 2025​

0.11.0 - 01 Aug 2025​

0.10.2 - 17 Jul 2025​

0.10.1 - 11 Jul 2025​

0.10.0 - 07 Jul 2025​

  • More fixes issues for nbclient stop.

0.9.0 - 02 Jul 2025​

  • Fix issues with nbmodel stops.

0.6.0 - 01 Jul 2025​