Skip to content

kernel.md

Latest commit

 

History

History
42 lines (29 loc) · 1.78 KB

kernel.md

File metadata and controls

42 lines (29 loc) · 1.78 KB
Raw

Kernel

Nodebook runs user code in a persistent Node.js child process per open notebook.

Detection

On startup the server reports the host Node version and process.execPath via GET /api/kernel/info. The UI shows kernel status: starting, idle, busy, or dead.

Lifecycle

  1. Opening/running a notebook calls POST /api/kernel/start with a notebookId (usually the file path).
  2. The manager spawns node server/src/kernel/runner.js with cwd set to the workspace root.
  3. Cells are executed over stdin/stdout as newline-delimited JSON.
  4. Restart Kernel kills the child and starts a fresh one (clears in-memory bindings; does not clear saved notebook outputs).
  5. Execution timeout defaults to 30s (NODEBOOK_CELL_TIMEOUT_MS).

What works in cells

  • require() of packages installed in the workspace node_modules
  • Node built-ins (fs, path, etc.) with workspace as cwd
  • Top-level await
  • Cross-cell state via var / bare assignment on the shared VM context (const/let are script-local when a cell uses await)

Safety model

Nodebook prioritizes process isolation over a hard sandbox:

  • One child process per notebook - a crash does not take down the server
  • Filesystem API paths are confined to the workspace root (no .. escapes)
  • No helper that runs arbitrary shell commands
  • Timeouts kill hung cells

This is a local developer tool. It does not claim to safely execute untrusted code. Treat notebooks like scripts you would run with node in that folder.

Environment

Variable Meaning
NODEBOOK_ROOT Workspace directory (default: ./workspace)
NODEBOOK_PORT HTTP port (default: 8787)
NODEBOOK_HOST Bind address (default: 127.0.0.1)
NODEBOOK_CELL_TIMEOUT_MS Per-cell timeout