Modal logo
Featured Getting started Hello, world Simple web scraper Serving Web Functions Large language models (LLMs) Deploy an OpenAI-compatible LLM service with vLLM Cut Ministral 3 cold start times by 10x with snapshots Maximize tokens per second in batch processing with vLLM Serve an ultra-low-latency chatbot with SGLang Deploy Nemotron 3 Serve Inkling-Small with SGLang Serve DeepSeek-V4-Flash Run a multimodal RAG chatbot to answer questions about PDFs Deploy a stateless MCP with FastMCP Images, video, & 3D Edit images with Flux Kontext Fine-tune Wan2.1 video models on your face Run Flux fast with torch.compile Animate images with LTX-Video Generate video clips with LTX-Video Run Stable Diffusion with a CLI, API, and web UI Audio Stream transcripts at the speed of speech using Kyutai STT Make music with ACE-Step Generate speech with Chatterbox Run high throughput batched transcription with Whisper Fine-tune Whisper to recognize new words Real-time communication (WebRTC) Serverless WebRTC WebRTC quickstart with FastRTC Computational biology Design protein binders with ESMFold2 Fold proteins with Chai-1 Build a protein-folding dashboard Fold proteins with Boltz-2 Modal Sandboxes Run Cursor Cloud Agents on Modal Build a scalable AI coding platform Create GIFs from Slack using the Claude Agent SDK Run a LangGraph agent's code in a secure GPU sandbox Watch a computer-use agent work in real-time over VNC Run massively parallel evals on Modal Sandboxes Build a stateful, sandboxed code interpreter Run Node.js, Ruby, and more in a Sandbox Speed up Sandbox starts with warm pools Inject secrets into outbound requests Reinforcement Learning Paint flowers with code Train coding agents Make LLMs better at math Embeddings Serve Liquid AI embeddings with Modal Servers Embed millions of documents with TEI Parallel processing and job scheduling Deploy a Hacker News Slackbot Run a Document OCR job queue Serve a Document OCR web app Training models from scratch Train an SLM with early-stopping grid search over hyperparameters Run long, resumable training jobs Hosting popular libraries YOLO: Fine-tune and serve computer vision models Blender: Build a 3D render farm Streamlit: Run and deploy Streamlit apps SQLite: Publish explorable data with Datasette Algolia: Build docsearch with a crawler Connecting to other APIs Google Sheets: Sync databases and APIs to a Google Sheet OpenAI: Run a RAG Q&A chatbot Tailscale: Add Modal Apps to your VPN Prometheus: Publish custom metrics with Pushgateway Managing data Mount S3 buckets in Modal Apps Build your own data warehouse with DuckDB, dbt, and Modal Miscellaneous
View on GitHub

Overview 

Quick snippet showing how to connect to a Jupyter notebook server running inside a Modal container, especially useful for exploring the contents of Modal Volumes. This uses Modal Tunnels to create a tunnel between the running Jupyter instance and the internet.

If you want to your Jupyter notebook to run locally and execute remote Modal Functions in certain cells, see the basic.ipynb example :)

import os
import subprocess
import time

import modal

app = modal.App(
    "example-jupyter-inside-modal",
    image=modal.Image.debian_slim(python_version="3.12").uv_pip_install(
        "jupyter", "bing-image-downloader~=1.1.2"
    ),
)
volume = modal.Volume.from_name(
    "modal-examples-jupyter-inside-modal-data", create_if_missing=True
)

CACHE_DIR = "/root/cache"
JUPYTER_TOKEN = "1234"  # Change me to something non-guessable!


@app.function(volumes={CACHE_DIR: volume})
def seed_volume():
    # Bing it!
    from bing_image_downloader import downloader

    # This will save into the Modal volume and allow you view the images
    # from within Jupyter at a path like `/root/cache/modal labs/Image_1.png`.
    downloader.download(
        query="modal labs",
        limit=10,
        output_dir=CACHE_DIR,
        force_replace=False,
        timeout=60,
        verbose=True,
    )
    volume.commit()

This is all that’s needed to create a long-lived Jupyter server process in Modal that you can access in your Browser through a secure network tunnel. This can be useful when you want to interactively engage with Volume contents without having to download it to your host computer.

@app.function(max_containers=1, volumes={CACHE_DIR: volume}, timeout=1_500)
def run_jupyter(timeout: int):
    jupyter_port = 8888
    with modal.forward(jupyter_port) as tunnel:
        jupyter_process = subprocess.Popen(
            [
                "jupyter",
                "notebook",
                "--no-browser",
                "--allow-root",
                "--ip=0.0.0.0",
                f"--port={jupyter_port}",
                "--NotebookApp.allow_origin='*'",
                "--NotebookApp.allow_remote_access=1",
            ],
            env={**os.environ, "JUPYTER_TOKEN": JUPYTER_TOKEN},
        )

        print(f"Jupyter available at => {tunnel.url}")

        try:
            end_time = time.time() + timeout
            while time.time() < end_time:
                time.sleep(5)
            print(f"Reached end of {timeout} second timeout period. Exiting...")
        except KeyboardInterrupt:
            print("Exiting...")
        finally:
            jupyter_process.kill()


@app.local_entrypoint()
def main(timeout: int = 10_000):
    # Write some images to a volume, for demonstration purposes.
    seed_volume.remote()
    # Run the Jupyter Notebook server
    run_jupyter.remote(timeout=timeout)

Doing modal run jupyter_inside_modal.py will run a Modal app which starts the Juypter server at an address like https://u35iiiyqp5klbs.r3.modal.host. Visit this address in your browser, and enter the security token you set for JUPYTER_TOKEN.