Python API

Use marimo_studio.authoring for a saved notebook on disk. Use marimo_studio.agent inside marimo code mode when an operation needs the current Studio tab. Code mode gives a coding agent a Python execution inside the live notebook kernel. Public records are frozen dataclasses. Their to_dict() methods produce the schema used by marimo-studio --json.

marimo_studio.authoring

open_workspace

from marimo_studio.authoring import open_workspace

workspace = open_workspace("analysis.py")

open_workspace(notebook: str | Path) -> Workspace

Returns a workspace handle for an existing regular file. The call resolves the path and verifies the file. It raises ConfigurationError when the resolved path is not a regular file. Each operation loads and validates the notebook and Studio configuration it needs.

Workspace

Workspace binds authoring operations to one notebook path.

await workspace.status() -> StudioOverview
await workspace.inspect_notebook(
    *,
    runtime: bool = False,
    include_code: bool = False,
    selectors: tuple[CellSelector, ...] = (),
    output_expressions: bool = False,
    context: Literal["selected", "upstream"] = "selected",
    limit: int | None = None,
    runtime_timeout: float = 60.0,
) -> InspectionResult
await workspace.starters() -> tuple[Starter, ...]
await workspace.create_view(name, *, starter=None) -> View
workspace.view(name) -> View
await workspace.bind(alias, cell, *, overwrite=False) -> BindingResult
await workspace.validate(
    *,
    level: Literal["static", "runtime"] = "static",
    view: str | None = None,
    runtime_timeout: float = 60.0,
) -> ValidationReport

Static notebook inspection never executes notebook code. Runtime inspection and runtime validation execute the complete notebook in an owned child process. The child inherits the interpreter environment, current directory, OS user permissions, filesystem access, and network access. The process boundary owns cleanup and terminates the child process tree after cancellation or a timeout. It is a lifecycle boundary, not a security sandbox. Run trusted notebook code.

Use context="upstream" with one or more selectors to include every cell that produces their inputs.

create_view() raises ViewExistsError when the name already has a view. view() reads the current catalog and returns a handle bound to that workspace and view incarnation. create_view() and bind() reject a replacement workspace with WorkspaceGenerationConflictError. Open a new workspace before retrying the operation.

StudioOverview

Describes the configuration source, notebook, view root, runtime choices, cell aliases, and configured views returned by Workspace.status(). generation identifies the returned catalog and changes when its configuration or view incarnations change.

In a marimohub session, persistence reports which files the hub saves when the session ends: "workspace" saves workspace files, "source" saves the notebook and its dependencies, and "none" saves nothing. It is None outside marimohub and before the hub publishes the session.

launch_requirements lists the exact Studio requirement with configured provider extras and the exact installed third-party provider distributions required to reopen the workspace in another uv environment. The uv executable must be available when Studio needs to prepare or re-enter that environment.

ViewOverview

Identifies one configured view, its project path, provider, Source document paths, default status, generation, and current artifact revision. Call View.inspect() to read each document's access mode.

InspectionResult

Contains the selected static notebook cells and optional runtime outputs and values returned by Workspace.inspect_notebook().

RuntimeProbe

Contains runtime cell state, serialized values, and rendered outputs for one completed runtime inspection.

RuntimeCell

Records one selected cell's terminal status, output summaries, and runtime errors.

RuntimeOutput

Summarizes one cell output by channel, media type, which identifies formats such as HTML or an image, and whether its payload is empty.

ValueReadResult

Maps requested value selectors to serialized values or ValueReadError records.

ValueReadError

Provides the stable code and message for one value that the runtime could not serialize or return.

OutputRenderResult

Maps requested output selectors to RenderedOutput or ValueReadError records.

RenderedOutput

Contains one rendered output's owner cell, MIME type, payload, timestamp, and UI object reset identifiers.

Starter

Describes one installed starter through id, title, summary, provider, the initial Source document plan in documents, and current availability. Run marimo-studio view create VIEW --target PATH --dry-run to inspect the complete created file set before committing it. Workspace.create_view() creates the view directly.

BindingResult

Identifies the alias, selected notebook cell, configuration path, and previous binding returned by Workspace.bind(). catalog_generation identifies the post-commit catalog captured by the owning workspace.

View

View binds view operations to one workspace and name. catalog_generation and generation identify the catalog and view incarnation that the handle observed.

Successful Workspace.bind(), Workspace.create_view(), View.make_default(), View.rename(), and View.remove() advance the owning Workspace. Existing View handles remain bound to their original generations. Use the handle that make_default() or rename() returns, or reacquire handles with workspace.view(name) after a catalog mutation.

Use Studio's remove and create operations for same-name replacement. Direct filesystem delete and recreation completed between observations is outside the 0.1 mutation-ownership contract when it reuses (device, inode, mode). This includes exact-byte recreation.

await view.inspect() -> ViewInspection
await view.read(path) -> ViewDocument
await view.write(path, content, *, expected_revision) -> ViewDocument
await view.build(*, profile="development") -> ViewBuild
await view.preview_url(
    *,
    runtime: str,
    exact: bool = False,
    server: str | None = None,
    access_token: str = "",
    browser_client: str = "",
) -> str
await view.hold_publication(*, owner: str, ttl: float = 300.0) -> PublicationHold
await view.release_publication(token: str) -> PublicationHold | None
await view.validate(
    *,
    level: Literal["static", "runtime"] = "static",
    runtime_timeout: float = 60.0,
) -> ValidationReport
await view.export(
    output,
    *,
    runtime: StaticRuntime = "zero-python",
    force: bool = False,
    prepare_timeout: float | None = None,
    progress: Callable[[StaticExportProgress], None] | None = None,
) -> StaticExportResult
await view.preflight(
    *,
    runtime: StaticRuntime = "zero-python",
    prepare_timeout: float | None = None,
    progress: Callable[[StaticExportProgress], None] | None = None,
) -> StaticPreflightReport
await view.make_default() -> View
await view.rename(new_name: str) -> View
await view.remove() -> ViewCatalog

make_default() serves the view at the main route (/) and returns a handle bound to the committed catalog. Selecting the current default leaves the catalog unchanged.

rename(new_name) moves the view project to new_name with its source, artifacts, and build history, and returns the handle for the new name. A default view stays the default. The project reads as stale until its next build(), which republishes it under the new name. Handles bound to the old name raise ViewGenerationConflictError from view operations such as inspect() and build(). rename() raises ViewExistsError for a taken name, including the view's own name, InvalidViewNameError for a name outside the view name rules, PublicationHeldError while a publication hold is active, and ViewRenameError when the project folder cannot move. The view keeps its old name after each of these errors.

remove() deletes the view project and returns the remaining views as a ViewCatalog. It raises LastViewError for the only view. ViewDeletionError reports an incomplete filesystem cleanup and exposes the cleanup path through diagnostic_details().

rename() and remove() raise ViewInUseError while another process holds an artifact lease for the view. Its processes detail lists the holding process IDs. WorkspaceMutationError reports a change that did not finish cleanly, so open a new Workspace before continuing. When its recovery names a renamed project folder, the view reloads under the new name, and marimo-studio view default VIEW repairs a default that still names the old one.

A catalog change after the handle was acquired, including a same-name replacement, makes make_default(), rename(), and remove() raise WorkspaceGenerationConflictError. Open a new Workspace and acquire the view again.

inspect() reads current filesystem state. Source can be edited through filesystem tools or write(). Provider inspection continues to own document access and build-input discovery. See Manage view source for multi-file edits and recovery.

write() checks the expected source revision under the same lock used by the Studio editor. A stale revision raises SourceConflictError and preserves the newer file.

show(), write(), build(), validate(), preflight(), and export() verify the handle's catalog and view generation. A same-name replacement raises ViewGenerationConflictError before browser activation, source writes, or artifact publication. export() checks again before replacing its destination, including when force=True.

preflight() builds, prepares, and inspects the complete static bundle in a temporary directory. It returns before publishing a caller-owned destination. export() runs the same preflight before it writes one static runtime. runtime="zero-python" prepares the configured notebook states. runtime="wasm" packages notebook source for execution through Pyodide in each visitor's browser. prepare_timeout bounds Prepared preparation and uses 30 seconds when omitted. Passing prepare_timeout with runtime="wasm" raises ValueError before Studio loads the workspace or builds the provider artifact.

progress receives ordered StaticExportProgress records from the synchronous export worker. Each record wraps either a marimo_export.ProgressEvent or a Studio-owned StaticExportStep. Keep callbacks fast and thread-safe. An exception raised by the callback cancels static destination publication.

build() returns the artifact revision produced by the selected development or production build. The profiles maintain independent publications. A failed build leaves the last successful artifact for that profile available.

preview_url()

Returns the running view's URL in a top-level browser document. Choose runtime="server", "wasm", or "zero-python" explicitly. The server must expose that runtime. Saved-workspace callers supply server, and the URL keeps its origin and path, including a proxy path prefix. A live code-mode view infers the local server address that marimo uses for callbacks, and follows the attached Studio tab. Behind a proxy, open the same path beneath the browser's public root. In a marimohub session, a code-mode URL uses the hub's public address for the sandbox. access_token authenticates the server request. On an edit-mode server, browser_client selects the Studio tab that a Python or Prepared preview follows. Either one requires server. The browser still needs the server's normal authentication.

The default URL follows the current presentation when opened or reloaded. exact=True requires current source to be built for the served profile (development in edit mode, production in run mode), then pins its presentation revision. Opening that URL returns HTTP 409 when the revision differs or view source is unbuilt or failed, even if the previous artifact is retained. This method returns an address and does not open or select a browser tab.

Finish code-mode execution before waiting for output in the browser. Wait for html[data-marimo-studio-state="ready"], then assert the application's content and behavior. The document's data-marimo-studio-revision records the committed presentation revision. Use inspect() for source and build freshness.

View.hold_publication and View.release_publication

await view.hold_publication(*, owner: str, ttl: float = 300.0) -> PublicationHold
await view.release_publication(token: str) -> PublicationHold | None

hold_publication() delays replacement publication across processes while source editing remains available. Existing published artifacts can be reused. owner identifies the editor and must contain 1 to 256 characters, including at least one non-whitespace character. ttl is a finite number of seconds greater than zero and at most 3600. Invalid arguments raise ValueError. An active hold raises PublicationHeldError with its owner and expiry.

Retain the returned token. In a later execution, (await view.inspect()).publication_hold returns the current hold with its token, or None when the view has no hold record. release_publication() releases the matching hold and returns its receipt. Repeating the release returns the same receipt. It returns None when the view has no hold record. A mismatched token raises ConfigurationError. Both methods enforce the handle's view generation. They remain available when the manifest needs repair.

Release or expiry permits the live editor to reconcile and publish current source. For an offline workflow, call build() after release. Source changes remain on disk after release, expiry, or editing-process exit.

PublicationHold

Contains token, owner, view generation, expires_at as Unix seconds, and released. The computed status is active, expired, or released. The computed expiry renders expires_at as UTC text, such as 2026-09-30 14:32:45 UTC. to_dict() includes status with the token, owner, generation, and expiry.

ViewBuild

ViewBuild(
    view: str,
    profile: Literal["development", "production"],
    revision: str,
    issues: tuple[ProjectDiagnostic, ...],
)

Describes one successful view build. revision identifies the complete browser output.

ViewDocument

Contains one authorized document's path, language, access mode, UTF-8 content, and current revision.

ViewInspection

Contains current filesystem and development publication evidence:

Field	Meaning
view, root, generation, catalog_generation	View name, project root, and observed ownership.
provider, documents, diagnostics	Provider, authorized Source catalog, and source-located repair diagnostics.
project_revision	Revision of observed build inputs, or None when unavailable. Interpret with files_complete.
published_project_revision	Source revision behind the retained development artifact, or None when unbuilt.
freshness, build	Development freshness and retained successful artifact.
latest_build	Latest development attempt, including its phase and diagnostics.
files, files_complete	Observed source and build-input inventory and whether discovery completed.
publication_hold	Current, expired, or released hold receipt, or None.

Provider or manifest failure returns diagnostics and an incomplete inventory. Repair view.toml through its manifest path, then inspect again. Artifact metadata describes disk publication. Browser assertions check one rendered presentation. See Identities and state for freshness values.

inspection.changes_since(previous: ViewInspection) -> ViewSourceChanges

Compares file revisions from two complete inventories. Raises ValueError when either inventory is incomplete or the root, view, or generation differs.

When view.toml needs repair, provider is None, the inventory is incomplete, and publication fields describe stored build receipts. Repair the manifest and inspect again to verify the provider and artifact.

ViewSourceFile

ViewSourceFile contains a project-relative path and content revision. A None revision records an expected file that is missing.

ViewSourceChanges

ViewSourceChanges contains added, modified, and deleted path tuples. Its to_dict() serializes each tuple as a list of forward-slash paths.

StudioDiagnostic

Names one source or build issue with a stable code, severity, repair hint, and optional source location.

StaticRuntime

Literal["zero-python", "wasm"]. The value selects the single notebook runtime written into a static export.

StaticExportResult

Contains notebook, view, selected runtime, provider artifact document, cache_activity, preflight, and marimo-export's DeliveryResult. The output, files, and warnings properties expose the committed delivery. A Prepared result carries marimo-export's authored and projection cache dispositions. A Browser result sets cache_activity to None. The entrypoint property resolves output / document. to_dict() emits the flattened output path, file count, warnings, and resolved entrypoint.

StaticExportProgress

Contains the selected view, runtime, event source, and nested event. source="marimo-export" preserves an upstream ProgressEvent unchanged. source="marimo-studio" carries a StaticExportStep for production build, bundle assembly, preflight, or commit. The returned result marks export completion.

StaticExportStep

Contains a Studio-owned kind and optional completed, total, elapsed_seconds, and message fields. Import ProgressEvent from marimo_export when code needs to distinguish preparation events from Studio steps. StaticExportEvent is the union of those two records.

StaticExportEvent

ProgressEvent | StaticExportStep. Inspect StaticExportProgress.source or the concrete event type when rendering owner-specific fields.

StaticPreflightReport

Contains the view, runtime, entry document, staged files, eligible browser_files, inspected_files, references, projections, and issues. ok is false when an issue has error severity. to_dict() returns the schema 1 machine record used by the CLI and StaticExportResult.

ProjectionPortability

Identifies one projection site_id, kind, optional target, static runtime, source location, reason, and status:

Status	Meaning
supported	The runtime accepts the projection model without prepared execution.
verification-required	Prepared still needs to capture the target's configured states.
verified	Prepared captured the target through the completed preflight.
incompatible	The selected runtime cannot represent the authored projection target.

StaticPreflightIssue

Names one source-located delivery diagnostic with code, severity, message, optional reference, and hint. Errors stop export before the destination changes. Warnings identify browser dependencies that require caller review.

ViewCatalog

ViewCatalog records the views of a notebook after a catalog change. View.remove() returns it. views maps each view name to its view generation in name order, default_view names the view at /, and catalog_generation identifies the committed catalog that the owning workspace captured.

ValidationReport

ValidationReport(
    notebook: Path,
    view: str | None,
    level: Literal["static", "runtime"],
    ok: bool,
    issues: tuple[ValidationIssue, ...],
    evidence: Mapping[str, object],
)

ok answers whether the requested validation completed against one coherent source and runtime state.

ValidationIssue

ValidationIssue(
    stage: Literal["validation", "static", "runtime"],
    severity: Literal["warning", "error"],
    code: str,
    message: str,
    advice: str,
    view: str | None = None,
    target: str | None = None,
    source: dict[str, object] | None = None,
)

Names one problem and the next repair action. Errors make ValidationReport.ok false. Warnings remain available for task-specific judgment.

doctor

await doctor(provider: str | None = None) -> ProviderReport

Returns installed view provider registrations, package versions, availability, and starter IDs. Pass a provider key to select one registration.

ProviderReport

Contains the provider registration records returned by doctor(). Each record includes its derived key, distribution, installed version, load state, availability, and starter IDs.

ProviderDiagnostic

Describes one installed provider registration, including its package identity, load error, provider metadata, availability, and discovered starter IDs.

marimo_studio.agent

import marimo_studio exposes this module as marimo_studio.agent. Studio loads it on first attribute access. For typed editor completion, import marimo_studio.agent directly.

Installed briefing

import agent_plugins as ap

print(ap.read("marimo-studio"))

Returns the installed core skill with its package identity and resource paths. help(marimo_studio.agent) includes the same briefing and Python API help. Reading instructions leaves the workspace and current view unchanged.

skill

skill() -> agent_plugins.Skill

Returns Studio's packaged marimo-studio skill. Read its body or a task-specific reference:

import marimo_studio

skill = marimo_studio.agent.skill()
print(skill.body)
print(skill.file("references/verification.md").read_text())

Raises AgentPluginError when the installed plugin has no usable Studio skill.

plugin

plugin() -> agent_plugins.Plugin

Returns the complete Agent Plugin bundled with the installed Studio version:

import marimo_studio

resources = marimo_studio.agent.plugin()
print(resources.tree())

Raises AgentPluginError when the installed distribution has no usable plugin.

current_workspace

import marimo_studio

workspace = marimo_studio.agent.current_workspace()

current_workspace() -> Workspace

Returns the live Workspace for the current code-mode notebook and Studio tab. Call it once in each code-mode execution.

Workspace

The live workspace supports the saved-notebook operations documented in marimo_studio.authoring. inspect_notebook() reads saved source, and runtime inspection executes a separate process. Neither returns the live kernel globals. Workspace-wide validation remains static or isolated runtime validation.

View

The live view supports preview_url() with the current server inferred from code mode. It also supports activation in the user's Studio tab:

await view.show() -> ShowResult

show() selects the view in the current Studio tab. Run it in a separate code-mode execution so the notebook can finish rendering. Open the URL returned by preview_url(runtime="server") with your preferred browser tool for direct page inspection.

The attached Studio server runs rename() and remove(), and first releases the artifacts it serves for the view. A failure raises AgentRequestError whose code names the error, such as view-exists or view-in-use, and whose details carry the same diagnostic details. Call show() on the handle that rename() returns to display the renamed view in the Studio tab.

ShowResult

ShowResult(
    notebook: Path,
    view: str,
    generation: int,
    session_id: str,
    client_id: str,
    *,
    preview_url: str,
    frame_selector: str,
)

Confirms that the intended Studio tab accepted the view selection. generation is the tab's monotonically increasing activation generation. It is distinct from the 64-character view generation used for mutation ownership. preview_url and frame_selector address the activated document in that Studio tab. View.preview_url() returns a separate top-level presentation URL.

PublicationHold

The live API returns the same publication hold record as saved-workspace authoring.

ViewInspection

The live API returns the same source inspection record as saved-workspace authoring. Its source evidence describes saved files.

ViewSourceFile

The live API uses the common file revision record.

ViewSourceChanges

The live API uses the common source comparison record.

ValidationReport

The live API returns the common validation record documented under marimo_studio.authoring.

ValidationIssue

The live API returns the common issue record documented under marimo_studio.authoring.

marimo_studio

agent

The agent module is available after importing Studio:

import marimo_studio

print(marimo_studio.agent.skill().body)

See marimo_studio.agent for installed instructions and the notebook-bound authoring API.

inspect_notebook

from marimo_studio import inspect_notebook

notebook = inspect_notebook("analysis.py", include_code=True)

inspect_notebook(path: str | Path, *, include_code: bool = False) -> NotebookSpec

Compiles the saved notebook and returns its cells, source spans, definitions, references, and dependency relationships without executing it.

create_asgi_app

from marimo_studio import create_asgi_app

app = create_asgi_app("analysis.py")

create_asgi_app(notebook: str | Path) -> ASGIApp

Returns a marimo run-mode ASGI application that serves the notebook's default and named views. ASGI is the standard interface between asynchronous Python web applications and servers. The application lifespan opens Studio services and closes its notebook sessions and background tasks during shutdown.

Forward the application lifespan through the ASGI server. marimo owns authentication and supplies read and edit scopes to Studio routes. The hosting stack owns TLS, proxy headers, process supervision, network exposure, and resource limits. See Compatibility and support.

marimo_studio.asgi:app reads the notebook path from MARIMO_STUDIO_NOTEBOOK for application servers:

MARIMO_STUDIO_NOTEBOOK=/srv/analysis/analysis.py \
  uvicorn marimo_studio.asgi:app --host 127.0.0.1 --port 8000

STUDIO_RESULT_SELECTOR

CSS selector for connected cell, output, and value hosts, parents containing hidden value hosts, custom regions annotated with data-marimo-lens-inputs, and authored regions marked with data-marimo-lens-target. See custom JavaScript rendering for the authoring contract.

Pass the selector to Lens to collect feedback from native projections and custom rendered regions:

from marimo_lens import Lens
from marimo_studio import STUDIO_RESULT_SELECTOR

studio_lens = Lens(dom_selector=STUDIO_RESULT_SELECTOR)

Render studio_lens through <marimo-output value="studio_lens"> in the view. Lens reads resolved producer and value-selector metadata from the linked hosts. Studio also publishes a document-local data-marimo-lens-scope on #app-shell so unannotated HTML can receive feedback. Its value is a CSS selector for preferred grouping regions, with the nearest block as a fallback. Set it in a view's source to choose that view's grouping policy. data-marimo-lens-target makes an explicit parent take precedence over smaller targets inside it. Give regions stable IDs to preserve feedback across rebuilds.

ASGIApp

Protocol for the asynchronous scope, receive, and send callable returned by create_asgi_app().

NotebookSpec

Static notebook inventory returned by inspect_notebook(). It provides by_ref(), named_cells(), and to_dict().

Errors

Catch MarimoStudioError for expected configuration, source, build, runtime, and live-browser failures:

from marimo_studio.errors import MarimoStudioError

try:
    await view.build()
except MarimoStudioError as error:
    print(error.code, error)

Every expected error exposes a stable code, CLI exit_code, HTTP status_code, retry classification, public hint, and structured diagnostic details. Catch a narrower class such as SourceConflictError, ViewNotFoundError, or RuntimeTimeoutError when the recovery differs.

The complete class, code, status, and recovery table is in Errors and JSON.

Public records

These tables list fields that have related names across command and Python surfaces. Nested notebook records are documented under NotebookSpec and InspectionResult.

Workspace and view records

Record	Fields
StudioOverview	notebook, state, generation, config_path, config_source, view_root, default_view, default_runtime, runtimes, bindings, views, launch_requirements, persistence
ViewOverview	name, generation, path, default, provider, documents, artifact_revision
Starter	id, title, summary, provider, documents, availability
BindingResult	alias, cell, config_path, catalog_generation, dry_run, previous_ref
ViewDocument	path, language, access, content, revision
ViewInspection	view, provider, documents, diagnostics, freshness, build
ViewBuild	view, profile, revision, issues
ViewCatalog	notebook, default_view, views, catalog_generation
StaticExportResult	notebook, view, runtime, document, cache_activity, preflight, delivery and computed output, files, warnings, entrypoint

StudioOverview.state is unconfigured, needs-view, or ready. ViewInspection.freshness is current, stale, unbuilt, building, or failed.

Provider records

Record	Fields
ProviderReport	providers
ProviderDiagnostic	registration, distribution, version, provider_key, error, info, availability, starters and computed loaded
ProviderAvailability	available, version, reason, action

ProviderDiagnostic.to_dict() emits key for provider_key, expands ProviderInfo into schema, title, summary, and api_version, and emits the qualified starter IDs.

Notebook inspection records

Record	Fields
InspectionResult	notebook, selected cells, optional runtime
NotebookSpec	path, revision, cells, app_config
CellSpec	ref, runtime_id, index, kind, name, source, code_sha256, preview, definitions, references, upstream, downstream, config, has_output_expression, may_display_output, markdown, optional code
RuntimeProbe	cells, values, outputs
RuntimeCell	status, outputs, errors
RuntimeOutput	channel, mimetype, empty
ValueReadResult	values, errors
OutputRenderResult	outputs, errors
ValueReadError	code, message
RenderedOutput	owner_cell_id, mimetype, data, timestamp, reset_ui_object_ids

InspectionResult.to_dict() embeds runtime cell state into selected cell records. Its top-level runtime field contains serialized values and value errors. RuntimeProbe.outputs remains available on the Python record for requested rendered output selectors.

Validation and browser records

Record	Fields
ValidationReport	notebook, view, level, ok, issues, evidence
ValidationIssue	stage, severity, code, message, advice, optional view, target, source
ShowResult	notebook, view, generation, session_id, client_id, preview_url, frame_selector

Static and runtime evidence contain named check records. Browser checks use the actual document's readiness and committed revision together with application assertions. Identities and state defines presentation and runtime identities.