Use Notebooks

Notebook sessions are service workloads. You can combine a notebook server with sandbox, SSH, and tmux plugins when you need both browser-based exploration and lower-level terminal access.

This page uses the quick-start project established in Create a project. The examples below show the Python client first, followed by the equivalent CLI command.

Start from a Hub Component

If your organization uses the public or organization component hub, start a notebook component and pass the queue or presets required by your cluster:

from polyaxon.client import RunClient

notebook_client = RunClient(project="quick-start")
notebook_run = notebook_client.create_from_hub(
    component="notebook",
    approved=True,
)
run_uuid = notebook_run.uuid
print(run_uuid)

polyaxon run -p quick-start --hub notebook

export RUN_UUID=PASTE_RUN_UUID_HERE

See the Jupyter Notebook integration for notebook-specific examples.

Add Sandbox Access to a Notebook Service

When authoring a custom notebook component, enable only the plugins you need:

kind: component
version: 1.1
name: notebook-sandbox

plugins:
  sandbox: true

run:
  kind: service
  ports:
    - 8888
  container:
    image: jupyter/scipy-notebook
    command: ["start-notebook.py"]

Add plugins.ssh: true only for native SSH or IDE access, and plugins.tmux: true only for reconnectable polyaxon ops shell sessions.

Common Workflow

1. Start the notebook service.
2. Open the notebook from the run page.
3. Use sandbox.process.exec() or polyaxon sandbox exec for quick checks outside the notebook kernel.
4. Use sandbox.fs or the sandbox upload and download commands to move small files.
5. Use SSH when you need IDE access or port forwarding.
6. Stop the run when the notebook is no longer active.

Track Experiments from a Notebook

When the notebook runs in-cluster, Polyaxon can resolve project and run context automatically. See tracking in notebooks for tracking examples.

See the Python run client and sandbox client references, or the sandbox CLI reference, for the full interfaces.