From 743a709fd5594a59f8b897ae125d22742409cc99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Mon, 29 Jun 2026 10:40:03 +0200
Subject: [PATCH] docs(jupyter): document configuring the kernel via deno.json

Document that the Deno Jupyter kernel reads a `deno.json` resolved from its
working directory, and that a notebook placed next to a `deno.json` picks up
its unstable features and permissions. Add a "Configuring the kernel" section
covering the `unstable` array and the new `permissions.jupyter` set, and
soften the top notice from a permanent "always runs with --allow-all"
limitation to "allow-all by default, but configurable".
---
 runtime/reference/cli/jupyter.md | 61 ++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 3 deletions(-)

diff --git a/runtime/reference/cli/jupyter.md b/runtime/reference/cli/jupyter.md
index 4d3c4c468..8370aaf34 100644
--- a/runtime/reference/cli/jupyter.md
+++ b/runtime/reference/cli/jupyter.md
@@ -11,10 +11,12 @@ Deno ships with a built-in Jupyter kernel that allows you to write JavaScript
 and TypeScript; use Web and Deno APIs and import `npm` packages straight in your
 interactive notebooks.
 
-:::caution `deno jupyter` always runs with `--allow-all`
+:::info `deno jupyter` runs with `--allow-all` by default
 
-Currently all code executed in the Jupyter kernel runs with `--allow-all` flag.
-This is a temporary limitation and will be addressed in the future.
+By default, code executed in the Jupyter kernel runs with all permissions
+granted. You can restrict what a notebook is allowed to do with a
+`permissions.jupyter` set in your `deno.json` — see
+[Configuring the kernel](#configuring-the-kernel).
 
 :::
 
@@ -49,6 +51,59 @@ notebooks.
 
 Jupyter Notebooks are available right out of the box.
 
+## Configuring the kernel
+
+The Deno kernel resolves a `deno.json` (or `deno.jsonc`) the same way the rest
+of the Deno CLI does: it starts from the kernel's working directory — which
+notebook frontends set to the notebook's directory — and walks up looking for a
+config file. Placing a `deno.json` next to your `.ipynb` therefore lets a
+notebook carry its own configuration, including an
+[import map](/runtime/fundamentals/modules/), unstable features, and
+permissions.
+
+### Unstable features
+
+Enable unstable APIs (such as `Deno.openKv()`) for a notebook by listing them in
+the `unstable` array:
+
+```json title="deno.json"
+{
+  "unstable": ["kv"]
+}
+```
+
+With this file next to the notebook, `await Deno.openKv()` works in a cell
+without any additional flags.
+
+### Permissions
+
+By default the kernel runs cells with all permissions granted. To scope what a
+notebook is allowed to do, define a `permissions.jupyter` set in `deno.json`:
+
+```json title="deno.json"
+{
+  "permissions": {
+    "jupyter": {
+      "env": ["OPENAI_API_KEY"],
+      "net": ["api.openai.com"],
+      "read": ["./data"]
+    }
+  }
+}
+```
+
+Cells then run with only those permissions, and accessing anything outside the
+set throws a `NotCapable` error. When no `jupyter` set is defined the kernel
+falls back to the `default` set, and when neither is defined it keeps granting
+all permissions, so existing notebooks are unaffected.
+
+:::info
+
+Specifying permissions in the config file is an experimental feature and may
+change in the future.
+
+:::
+
 ## Rich content output
 
 [`Deno.jupyter`](/api/deno/~/Deno.jupyter) namespaces provides helper function