> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalph.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed Notebooks

> Add interactive Jupyter notebooks to any website with a single iframe

## Why

You wrote a notebook. Now you want it on your blog, in your docs, or inside a course. Alph embeds are a single `<iframe>` — paste it anywhere HTML works.

## Quick Start

```html theme={null}
<iframe
  src="https://runalph.ai/embed/{org}/{notebook-slug}"
  width="100%" height="400" frameborder="0"
  style="border-radius: 8px; border: 1px solid #e5e7eb;">
</iframe>
```

Replace `{org}` with your organization slug and `{notebook-slug}` with the notebook slug. Both are visible in the notebook URL.

<Note>Only **public** notebooks can be embedded.</Note>

## Embed Builder

The fastest way to configure an embed is the visual builder at [runalph.ai/embed](https://runalph.ai/embed).

<Steps>
  <Step title="Enter your notebook">
    Set the organization slug and notebook slug. The preview updates live.
  </Step>

  <Step title="Configure display">
    Choose which cells to show, pick a theme, and toggle source code or output visibility.
  </Step>

  <Step title="Copy the embed code">
    Click **Copy** to grab the iframe snippet and paste it into your site.
  </Step>
</Steps>

The builder also has a **Manage** tab where you can view, pause, or delete your managed embed configurations.

## URL Parameters

Control what the embed shows by adding query parameters to the iframe `src`.

| Parameter     | Example            | Description                                                    |
| ------------- | ------------------ | -------------------------------------------------------------- |
| `cell`        | `cell=2`           | Show a single cell by index (0-based)                          |
| `cells`       | `cells=0,2-5,8`    | Show specific cells — indices, ranges, or both                 |
| `cellId`      | `cellId=abc123`    | Show a cell by its metadata ID                                 |
| `theme`       | `theme=dark`       | Force `light` or `dark`. Omit to inherit from the parent page. |
| `showSource`  | `showSource=0`     | Hide source code (show outputs only)                           |
| `showOutput`  | `showOutput=0`     | Hide outputs (show source only)                                |
| `embedConfig` | `embedConfig={id}` | Enable managed execution (see below)                           |

### Examples

Show only cells 0 through 3 in dark mode, outputs only:

```
https://runalph.ai/embed/my-org/my-notebook?cells=0-3&theme=dark&showSource=0
```

Show a single cell by metadata ID:

```
https://runalph.ai/embed/my-org/my-notebook?cellId=train-model
```

## Execution Modes

Embeds support two ways for viewers to run code.

### Standard

Viewers see the notebook's saved source and outputs. Signed-in Alph users can connect their own project to execute cells directly.

No extra configuration needed — this is the default.

### Managed

Your project powers the embed. Execution is proxied through Alph so your Jupyter credentials are never exposed to viewers. Only the notebook's existing cell sources can be run.

<Steps>
  <Step title="Open the Embed Builder">
    Go to [runalph.ai/embed](https://runalph.ai/embed) and switch the Execution section to **Managed**.
  </Step>

  <Step title="Select an org and project">
    Pick the organization and project that will back execution. The project must be active.
  </Step>

  <Step title="Create the configuration">
    Click **Create embed configuration**. The builder adds the `embedConfig` parameter to your snippet automatically.
  </Step>
</Steps>

You can manage configurations from the **Manage** tab — pause, resume, or delete them at any time.

## Security

* Only public notebooks can be embedded
* Managed mode never exposes your Jupyter token to viewers
* Only the notebook's existing cell code can be executed — arbitrary code is rejected
* Execution is rate-limited per embed configuration
* Concurrent sessions are capped per configuration

## Sizing Tips

The embed renders at whatever size the iframe allows. A few recommendations:

* **Full notebook:** `width="100%" height="600"` or larger
* **Single cell:** `width="100%" height="300"` is usually enough
* **Responsive:** use CSS to make the iframe fill its container

```html theme={null}
<div style="position: relative; width: 100%; padding-bottom: 56.25%; height: 0;">
  <iframe
    src="https://runalph.ai/embed/my-org/my-notebook?cell=0"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;
           border-radius: 8px; border: 1px solid #e5e7eb;"
    frameborder="0">
  </iframe>
</div>
```