App Mode and Sharing

Present a saved notebook with Open as: App, understand what App mode changes, and validate a workbook before sharing it with other Excel users.

App mode is an optional presentation of the same notebook, not a separate application or security boundary. Use it when another user should interact with controls and outputs without the full authoring surface, then validate the saved workbook in Excel before distribution.

App mode

App mode is an optional presentation of the same notebook. It is useful when a notebook has become a repeatable application or internal workflow and another user should focus on controls, explanations, tables, charts, and outputs rather than editing Python source.

It is not a separate application project and it is not required to receive value from the notebook.

AuthorEdit mode

↓

Workbook userApp mode

The change is primarily presentation: the authoring controls disappear, while notebook controls, explanations, tables, charts, and reactive outputs remain available to the workbook user.

Choose Open as: App

In an Edit session:

1. save the notebook at least once;
2. choose App from Open as: in the Boardflare footer;
3. save the notebook again;
4. wait for Boardflare to report Saved;
5. reopen the notebook.

The next session opens in the focused app-style presentation.

Changing Open as does not switch the current session. The setting is a saved startup preference.

Return to editing

In App mode, use the pencil/edit action to open a fresh Edit session for the current session.

That action does not silently change the saved opening preference. If the workbook should open in Edit mode next time, choose Open as: Edit and save that preference from an Edit session.

What App mode changes

App mode hides the normal Boardflare navigation/status footer and presents the notebook as a full-pane read-style experience. Notebook controls and reactive outputs remain useful because they are part of the notebook itself.

A good App-mode notebook usually emphasizes:

• clear instructions and Markdown;
• controls with business labels;
• important result tables and charts;
• validation or warning messages;
• minimal implementation detail in the visible presentation.

What App mode does not change

App mode is not:

• source-code protection;
• a permissions boundary;
• a separate deployed application;
• a replacement for reviewing executable workbook source;
• a requirement for BF.OUTPUT() or BF.FUNCTION().

The saved notebook source still travels with the workbook and should be trusted like other executable code.

When to use it

Use App mode when the notebook has become a repeatable interactive tool for someone who does not need the authoring surface.

Stay in Edit mode when the primary job is analysis, model development, debugging, explanation, or ongoing notebook maintenance.

See Sharing and trust before distributing a workbook that contains executable notebook source.

Sharing and trust

A Boardflare notebook can remain personal analysis or be shared with other workbook users. When you distribute a notebook-enabled workbook, treat the saved Python source as executable code and validate the workflow another user will open.

What is saved and what is rebuilt

flowchart LR
    subgraph Saved_with_workbook[Saved with the Excel workbook]
      A[Notebook source]
      B[Saved presentation: Edit or App]
      C[Worksheet formulas such as BF.OUTPUT / BF.FUNCTION]
    end

    subgraph Rebuilt_on_open[Recreated when the notebook runs]
      D[Pyodide / Python kernel]
      E[marimo reactive graph]
      F[Workbook input subscriptions]
      G[Anywidget models]
      H[Published values + callables]
    end

    A --> D
    B --> E
    D --> E
    E --> F
    E --> G
    G --> H
    C --> H

In Excel, Boardflare stores notebook source and the preferred Edit/App opening presentation on the hidden _BOARDFLARE worksheet. A successful save writes the content, reads it back, and verifies that the stored source and metadata match.

The workbook does not persist a live Python kernel, Python objects, active function invocations, reactive state, or output/function registries.

Recipient requirements

A recipient needs:

• the workbook;
• the Python for Excel add-in;
• network access to the add-in/notebook assets required by the deployment;
• organizational permission to run the workbook and its executable Python source.

The recipient does not need a separate desktop Python installation.

If an organization blocks the add-in or required notebook runtime assets, the notebook may not start. Treat those deployment dependencies as part of the workbook’s operating requirements.

Cold start from worksheet formulas

A workbook can need the Python runtime before the user has opened the visible Notebook tab.

sequenceDiagram
    participant Excel
    participant Shared as Boardflare shared runtime
    participant Notebook as marimo/Pyodide
    participant Formula as BF.OUTPUT / BF.FUNCTION

    Excel->>Formula: Recalculate saved formula
    Formula->>Shared: Subscribe to notebook result
    Shared->>Notebook: Restore saved source and start session
    Notebook->>Notebook: Hydrate bf.inputs and run reactive graph
    Notebook->>Shared: Claim bf.publish registry
    Shared-->>Formula: Push published value/function result

During this sequence, Excel can show #BUSY!. That is normal while the notebook/publication registry is still starting. The task pane does not have to be visible for normal formula cold start.

App mode

App mode presents the same saved notebook as a simplified interactive experience and hides code cells during normal use. It is useful when an analysis has become a repeatable tool and another user should focus on inputs, controls, explanations, and outputs rather than the implementation.

App mode is not:

• a permissions boundary;
• source encryption;
• a DRM mechanism;
• a guarantee that the recipient cannot return to Edit mode.

Do not put a secret in notebook source on the assumption that App mode hides it.

Executable workbook trust

Notebook source is executable Python and can run automatically when a trusted workbook opens in App mode. Before using a workbook with sensitive data, know:

• who authored and reviewed it;
• which worksheet ranges it reads;
• which outputs/functions it publishes;
• which third-party packages it imports;
• which workbook data it reads and what it publishes back;
• who owns the notebook when business rules change.

Cross-origin notebook isolation reduces unintended capability access; it does not make arbitrary authored Python trustworthy. See Security and data flow.

Expected startup/recovery states

State	Meaning	What a user should do
#BUSY!	Notebook/publication is still starting	Wait; if persistent, open Notebook to inspect status
Notebook not running	Session stopped or failed	Retry/restart the notebook session
Unknown output/function	Requested name was not published	Contact author or inspect current bf.publish() in Edit mode
Dependency/import error	A required browser-Python dependency is unavailable or incompatible	Check Pyodide/browser compatibility and the notebook error, then retry
Save/source error	Stored notebook could not be loaded or verified	Use recovery/reset only when discarding/replacing saved source is acceptable

Pre-sharing checklist

• Save until Boardflare reports the notebook saved.
• Close and reopen the workbook.
• Verify the intended Edit/App presentation.
• Verify every BF.OUTPUT() consumer.
• Verify every BF.FUNCTION() consumer, including optional arguments used in the workbook.
• Change representative workbook inputs and confirm reactive updates.
• Test invalid/missing inputs and the user-facing error message.
• Test required third-party imports in a fresh session when the notebook depends on them.
• Add user instructions and an owner/contact.
• Have a second user open and use the workbook without author intervention.

Validate in Excel

Excel has its own persistence and streaming custom-function lifecycle behavior, so validate both in Excel itself.

Before distributing an Excel workbook, validate save/reopen, cold start, formula results, and recipient behavior in the actual Excel add-in.