Nebula Notebook

Nebula is an agent-native notebook computing environment built for what's coming next: real Jupyter kernels, real filesystem access, and a notebook that agents (Claude Code, Codex, …) can drive end-to-end through MCP — while staying a fast, polished notebook even if you never touch the AI features.

Quick Start

npx nebula-notebook

On first start, a QR code will appear in the terminal. Scan it with an authenticator app (Google Authenticator, Authy, etc.) to set up 2FA.

Open http://localhost:3000 and enter your 6-digit code.

To let agents (Claude Code, Codex, Cursor, Gemini CLI, …) drive your notebooks, register the Nebula MCP on the machine where your agent runs:

npx nebula-notebook-mcp setup-mcp

Then open a notebook, click Agent, and launch Claude Code or Codex right in the notebook's terminal.

From source (latest)

npm releases are point-in-time snapshots — to get the latest changes, install from source:

git clone https://github.com/jzthree/nebula-notebook.git
cd nebula-notebook
npm install

npm run start

Root Directory

Set the server root directory (default is your home directory):

npm run start --workdir /path/to/projects

This root is used for the file browser and terminals. You can also change it from the file browser UI and it will be remembered by the server.

Features

Core

• Real Jupyter kernel execution (Python, Julia, R, etc.)
• Real filesystem access - open notebooks from anywhere
• Autosave with crash recovery
• Undo/redo with full edit history

Navigation

• Table of Contents breadcrumb - auto-generated from markdown headers
• Search & replace across all cells (Cmd/Ctrl+F)
• Keyboard shortcuts (Shift+Enter to run, Cmd+S to save, etc.)

Agents

• Agent terminal built into every notebook — one click launches Claude Code or Codex, pre-briefed with the server URL and notebook path
• "Fix with agent" on any failing cell, and per-cell prompts, injected straight into the agent's terminal
• Full MCP toolset (nebula-notebook-mcp): read/edit/execute cells, manage kernels and files — from any agent on any machine
• Agent sessions lock the notebook during edits and sync live into the UI

Editor

• Syntax highlighting with CodeMirror
• Tab autocomplete for variables
• Auto-indent detection
• Execution queue with status indicators

UI/UX

• Virtualized cell list for large notebooks
• Collapsible/resizable outputs
• Rich interactive outputs, including Plotly MIME rendering and Nebula-native JS outputs
• Sound & browser notifications for long-running cells
• Dark-mode friendly error display

Rich Outputs

Nebula supports structured rich notebook outputs instead of flattening everything to plain text.

• Jupyter-compatible Plotly rendering via application/vnd.plotly.v1+json
• Nebula-native interactive outputs via application/vnd.nebula.web+json

See docs/RICH_OUTPUTS.md for examples, payload format, shared library loading, and current compatibility limits.

Prerequisites

• Node.js 18+
• Python 3.10+ with Jupyter kernels (pip install ipykernel)

Project Structure

nebula-notebook/
├── components/       # React components
├── hooks/            # Custom React hooks
├── lib/              # Core utilities (diff, operations)
├── services/         # Frontend API clients
├── node-server/      # Node.js Express backend
│   └── src/
│       ├── index.ts          # Server entry point
│       ├── kernel/           # Jupyter kernel management (ZeroMQ)
│       ├── cluster/          # Multi-server cluster support
│       ├── auth/             # 2FA authentication
│       └── routes/           # API routes
├── packages/
│   └── mcp/          # Separately installable MCP adapter package
└── types.ts

MCP Adapter

The MCP adapter is published as nebula-notebook-mcp and lives in this repository under packages/mcp. It is a separate package so it can be installed on a local agent/client machine even when the Nebula Notebook server is running elsewhere.

# Register the MCP with your installed agent CLIs (Claude Code, Codex, …)
npx nebula-notebook-mcp setup-mcp

# Agents must call connect_server(base_url) once per session —
# the base_url is the URL you open Nebula at, e.g. http://localhost:3000

# From a repo checkout instead: build or run the MCP server
npm run mcp:build
npm run mcp

Authentication

Nebula uses TOTP-based two-factor authentication:

1. First Start: QR code printed to terminal - scan with authenticator app
2. Login: Enter 6-digit code in browser
3. Trust Browser: Check option for 30-day sessions

Config stored in ~/.nebula/auth.json. Multiple servers sharing the same home directory share the same 2FA.

To print the QR code again later (for re-enroll/recovery), run:

npm run auth:qr

Disable 2FA (local/dev)

Run the server with auth disabled:

npm run start --noauth

You can also use an env var if preferred:

NO_AUTH=true npm run start

Preserve + Reattach Kernels (dev)

To keep kernels running across dev server restarts and reattach on startup:

NEBULA_PRESERVE_KERNELS=true NEBULA_REATTACH_KERNELS=true npm run start

CLI flags are also supported when running the node server directly:

cd node-server
npm run dev -- --preserve-kernels --reattach-kernels

Multi-Server Cluster

Run kernels on multiple machines while accessing them from a single UI. Useful for:

• Offloading compute to more powerful servers
• Using different Python environments on different machines
• Distributed team setups with shared filesystem

Setup

Main Server (the one you access in the browser):

npm run start

Client Server (additional compute nodes):

export NEBULA_MAIN_SERVER=http://main-server-hostname:3000
export NEBULA_SERVER_NAME="GPU Server"  # optional display name
npm run start -- --client

The client will automatically register with the main server and appear in the kernel menu.

Usage

1. Click the kernel indicator in the toolbar
2. If multiple servers are registered, a Server section appears at the top
3. Select a server to run your kernels on that machine
4. Kernels, interrupt, and restart all work transparently across servers

Security

For production deployments, set a shared secret on all servers:

export NEBULA_CLUSTER_SECRET="your-secret-key"

If your clients share the same filesystem as the main server, you can also copy ~/.nebula/cluster.json from the main server instead of setting the env var.

Servers without the correct secret will be rejected during registration.

Requirements

• All servers must have network access to each other
• Client servers need access to the same filesystem paths as the main server (for notebook files)
• Each server runs its own Jupyter kernels locally

Tips

Persistent Terminals: Access standalone terminals via URL:

http://localhost:3000/?terminal=dev
http://localhost:3000/?terminal=logs

Terminals persist as long as the server runs. Bookmark different terminals for quick access.

Tech Stack

• Frontend: React 19, TypeScript, Vite, Tailwind CSS, CodeMirror
• Backend: Node.js, Fastify, ZeroMQ (Jupyter kernel protocol)
• Auth: TOTP (otplib), JWT (jsonwebtoken)
• Agents: MCP (nebula-notebook-mcp) driven by Claude Code, Codex, and other agent CLIs

License

MIT