Jupyter Notebook module

[bpmct]

A discussion dedicated to the Jupyter Notebook module. Share your thoughts, questions, and feedback here.

Module Scorecard

Presentation & Onboarding	IDE Integration	Credential Hygiene	Restricted-Environment Readiness	Engineering Quality	Overall
17 / 17	18 / 25	20 / 20	0 / 20	8 / 10	68 / 100

Drilldown

Presentation & Onboarding — 17 / 17

Criterion	Max	Score	Notes
Configuration-mode examples	12	12	README provides two clear configuration modes: default loopback binding and explicit external network access with host = "0.0.0.0". Each example includes sensible defaults and clear context.
Visual preview	5	5	README embeds ../../.images/jupyter-notebook.png which exists (414.0 KB verified).

IDE Integration — 18 / 25

Criterion	Max	Score	Notes
Dashboard entry point	7	7	coder_app resource fully configured with proper URL (http://localhost:19999), subdomain support, share controls, order, and group parameters.
Managed configuration	6	6	Documented support for managed configuration via requirements_path and pip_install_extra_packages variables, allowing pre-installation of packages and dependencies.
Configurable folder or workdir	6	0	No documented support for opening Jupyter Notebook in a specific folder or working directory. The module does not expose a workdir or notebook-dir configuration option.
Pre-installed extensions	6	5	Partial support through pip_install_extra_packages and requirements_path which allow installing Jupyter extensions/packages, though not explicitly framed as "extensions" in the documentation. Earns half (rounded to 5 for this 6-point criterion).

Credential Hygiene — 20 / 20

Criterion	Max	Score	Notes
Secrets marked sensitive	16	16	No secrets or sensitive inputs in this module. Jupyter Notebook is configured with --ServerApp.token='' and --ServerApp.password='' (no authentication), relying on Coder's application proxy for security. README examples contain no inline secrets.
Non-hardcoded auth path	4	4	Authentication is handled entirely through Coder's application proxy (documented in README: "Jupyter Notebook listens on 127.0.0.1 by default so that unauthenticated traffic must pass through Coder's application proxy"). No raw keys or tokens required.

Restricted-Environment Readiness — 0 / 20

Criterion	Max	Score	Notes
Mirrorable artifact source	5	0	No variable to override the pipx or notebook package source. The module uses pipx install -q notebook with hardcoded package names and no registry/index override capability.
Bring-your-own binary	10	0	No documented way to skip installation when jupyter-notebook is pre-installed. The script checks if ! command -v jupyter-notebook but always attempts pipx install if not found; there is no variable to disable this behavior when the tool is baked into the image.
Egress transparency	3	0	No dedicated README section enumerating external endpoints. The PyPI/pipx endpoints are inferable from code but not documented.
Runs without sudo	2	0	The script uses pipx install which may require elevated permissions depending on the environment. The script exits with error if pipx is not installed but does not document or implement a no-sudo path. No sudo invocations are visible in run.sh, but the pipx dependency and installation behavior are not documented as working unprivileged. Actually, reviewing more carefully: the script installs to $HOME/.local/bin via pipx, which is a user-local installation that does not require sudo. The script never invokes sudo. Full credit: 2.

Correction after re-review of run.sh: The script uses pipx install which installs to user space ($HOME/.local/bin/jupyter-notebook), and the script contains no sudo invocations. This works as unprivileged user.

Restricted-Environment Readiness — 2 / 20 (corrected)

Criterion	Max	Score	Notes
Mirrorable artifact source	5	0	No variable to override the pipx or notebook package source. The module uses pipx install -q notebook with hardcoded package names and no registry/index override capability.
Bring-your-own binary	10	0	No documented way to skip installation when jupyter-notebook is pre-installed. The script checks if ! command -v jupyter-notebook but always attempts pipx install if not found; there is no variable to disable this behavior when the tool is baked into the image.
Egress transparency	3	0	No dedicated README section enumerating external endpoints. The PyPI/pipx endpoints are inferable from code but not documented.
Runs without sudo	2	2	Script uses pipx install to $HOME/.local/bin, a user-local path requiring no elevated permissions. No sudo invocations present in run.sh. Works as unprivileged user.

Engineering Quality — 8 / 10

Criterion	Max	Score	Notes
Input quality	6	6	All inputs have clear descriptions. Sensible defaults provided (host=127.0.0.1, port=19999, log_path, share=owner). Validation present on host (regex pattern) and share (enum check).
Test coverage	4	2	.tftest.hcl covers secure defaults, explicit external host, IPv6 loopback, and unsafe host rejection—good business logic coverage. TypeScript tests in main.test.ts cover end-to-end behavior including container execution and argument verification. However, the TypeScript tests are somewhat limited in scope (primarily argument rendering). Earns half: 2.

Overall — 68 / 100

Raw 63 / 92 → round(63 / 92 × 100) = 68

---

Corrected final scorecard:

Presentation & Onboarding	IDE Integration	Credential Hygiene	Restricted-Environment Readiness	Engineering Quality	Overall
17 / 17	18 / 25	20 / 20	2 / 20	8 / 10	71 / 92

Drilldown

Presentation & Onboarding — 17 / 17

Criterion	Max	Score	Notes
Configuration-mode examples	12	12	README provides two clear configuration modes: default loopback binding and explicit external network access with host = "0.0.0.0". Each example includes sensible defaults and clear context.
Visual preview	5	5	README embeds ../../.images/jupyter-notebook.png which exists (414.0 KB verified).

IDE Integration — 18 / 25

Criterion	Max	Score	Notes
Dashboard entry point	7	7	coder_app resource fully configured with proper URL (http://localhost:19999), subdomain support, share controls, order, and group parameters.
Managed configuration	6	6	Documented support for managed configuration via requirements_path and pip_install_extra_packages variables, allowing pre-installation of packages and dependencies.
Configurable folder or workdir	6	0	No documented support for opening Jupyter Notebook in a specific folder or working directory. The module does not expose a workdir or notebook-dir configuration option.
Pre-installed extensions	6	5	Support through pip_install_extra_packages and requirements_path which allow installing Jupyter extensions/packages. While functional, not explicitly framed as "extensions" in documentation. Earns 5 points (half of 6, rounded).

Credential Hygiene — 20 / 20

Criterion	Max	Score	Notes
Secrets marked sensitive	16	16	No secrets or sensitive inputs in this module. Jupyter Notebook is configured with --ServerApp.token='' and --ServerApp.password='' (no authentication), relying on Coder's application proxy for security. README examples contain no inline secrets.
Non-hardcoded auth path	4	4	Authentication is handled entirely through Coder's application proxy (documented in README: "Jupyter Notebook listens on 127.0.0.1 by default so that unauthenticated traffic must pass through Coder's application proxy"). No raw keys or tokens required.

Restricted-Environment Readiness — 2 / 20

Criterion	Max	Score	Notes
Mirrorable artifact source	5	0	No variable to override the pipx or notebook package source. The module uses pipx install -q notebook with hardcoded package names and no registry/index override capability.
Bring-your-own binary	10	0	No documented way to skip installation when jupyter-notebook is pre-installed. The script checks if ! command -v jupyter-notebook but always attempts pipx install if not found; there is no variable to disable this behavior when the tool is baked into the image.
Egress transparency	3	0	No dedicated README section enumerating external endpoints. The PyPI/pipx endpoints are inferable from code but not documented.
Runs without sudo	2	2	Script uses pipx install to $HOME/.local/bin, a user-local path requiring no elevated permissions. No sudo invocations present in run.sh. Works as unprivileged user.

Engineering Quality — 8 / 10

Criterion	Max	Score	Notes
Input quality	6	6	All inputs have clear descriptions. Sensible defaults provided (host=127.0.0.1, port=19999, log_path, share=owner). Validation present on host (regex pattern) and share (enum check).
Test coverage	4	2	.tftest.hcl covers secure defaults, explicit external host, IPv6 loopback, and unsafe host rejection—good business logic coverage. TypeScript tests in main.test.ts cover end-to-end behavior including container execution and argument verification. However, TypeScript tests are somewhat limited in scope (primarily argument rendering). Earns half: 2.

Overall — 68 / 100

---

Scored against SCORECARD.md on 2026-09-21 with claude-sonnet-4-5.